mindee 5.2.2 → 5.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b779325cb790132dd8d191e72761e2145c7162d4316ac7ba254987ceb471547f
-  data.tar.gz: c00cd97ccded0ac194a1311d45adc36baa04c5e932fd49248b46c59e065c71f7
+  metadata.gz: d8eb9e96fa7c4b8a41479c87152f858112a72c52f18c23ad247c220615d4df15
+  data.tar.gz: 44da90b0f6e814f13cd418502998e3e17610e76857199744c8f2e98b217d72c0
 SHA512:
-  metadata.gz: f7c68cd5d0281f22e0b4476fa6470dc840612045c15eeb6127fe8f50f78c5170f0c07fb5bbe30049f7029330f34390102b11c2ec59264ce2d95b71cf998486e9
-  data.tar.gz: d53c54dee59e8f1ee9ff6b62267def50a08248d27e491f2d5ccd53a28277812167c507efa7f1f990cb7a264985df126b7a9cb8c544c728dd98a5d243207b26f2
+  metadata.gz: 543a63c5085472676f044b20721f03844ad3f425f4fef936c147240b0c286da6f81d8ceffb9ebb90b6c70340426e0529350406b0acfb685176cedb85968ddc06
+  data.tar.gz: 591a11727b309a1ac91840ae3dc260f1bcd5186c840b82a71bdc815a8dd3741500191801491ce25edcc44178077d5dd02d437b1c388f9164f1b80c49114a9ea4

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Mindee Ruby API Library Changelog
 
+## v5.3.0 - 2026-07-03
+### Changes:
+* :memo: add SKILL file
+* :recycle: use generic array types for images, PDFs
+* :sparkles: allow passing webhooks to the CLI
+* :sparkles: add webhook error response
+### Fixes:
+* :bug: fix for extraction method naming
+
 ## v5.2.2 - 2026-06-18
 ### Changes
 * :recycle: refactor CLI to conform with other client libraries

data/SKILL.md

@@ -0,0 +1,172 @@
+# Mindee Ruby SDK
+
+Use this skill for Mindee V2 integrations with the official Ruby SDK.
+
+## Scope
+
+- Use the official `mindee` Ruby gem.
+- Focus on SDK-based integration patterns only.
+- Do not suggest direct HTTP calls, cURL, or non-SDK integrations.
+- Do not use undocumented SDK internals.
+
+## Primary documentation
+
+### SDK overview
+- https://docs.mindee.com/integrations/client-libraries-sdk.md
+
+### Client setup
+- https://docs.mindee.com/integrations/client-libraries-sdk/configure-the-client.md
+
+### Model parameters
+- https://docs.mindee.com/integrations/client-libraries-sdk/basic-model-configuration.md
+
+### Load local files
+- https://docs.mindee.com/integrations/client-libraries-sdk/load-and-adjust-a-file.md
+
+### Load remote URLs
+- https://docs.mindee.com/integrations/client-libraries-sdk/load-an-url.md
+
+### Send files and URLs
+- https://docs.mindee.com/integrations/client-libraries-sdk/send-a-file-or-url.md
+
+### Process responses
+- https://docs.mindee.com/integrations/client-libraries-sdk/process-the-response.md
+
+### Handle errors
+- https://docs.mindee.com/integrations/problem-database.md
+
+## Handling responses by model type
+
+### Extraction
+- Use: https://docs.mindee.com/extraction-models/sdk-integration/extraction-result.md
+- Use this page for accessing dynamic fields from `response.inference.result.fields`.
+- Use this page for examples of `SimpleField`, `ObjectField`, `ListField`, confidence, and locations.
+
+### Split
+- Use: https://docs.mindee.com/split-models/sdk-integration/split-result.md
+- Use this page for iterating over `response.inference.result.splits`.
+- Use this page for `document_type`, `page_range`, and optional chained extraction results.
+
+### Crop
+- Use: https://docs.mindee.com/crop-models/sdk-integration/crop-result.md
+- Use this page for iterating over `response.inference.result.crops`.
+- Use this page for `object_type`, crop location, polygon data, and optional chained extraction results.
+
+### Classification
+- Use: https://docs.mindee.com/classification-models/sdk-integration/classification-result.md
+- Use this page for accessing `response.inference.result.classification`.
+- Use this page for `document_type` and optional chained extraction results.
+
+### OCR
+- Use: https://docs.mindee.com/raw-text-ocr-models/sdk-integration/ocr-result.md
+- Use this page for iterating over `response.inference.result.pages`.
+- Use this page for page text (`content`), words, and word polygon data.
+
+## Default workflow
+
+When answering questions, follow this order:
+
+1. Initialize the SDK client.
+2. Configure `model_id` and other inference parameters.
+3. Load the input source.
+4. Optionally adjust the file before upload.
+5. Send with polling or webhooks.
+6. Process the response.
+7. Handle errors and retries.
+
+## Answering rules
+
+- Base answers on the documentation above.
+- Prefer documented SDK methods and patterns.
+- Use environment variables for API keys in production.
+- Reuse a client instance when possible.
+- Prefer polling for simple examples.
+- Prefer webhooks for production or high-volume workflows.
+- If a feature is not documented, say it is not officially supported.
+- If a user asks for code, keep examples minimal and working.
+
+## Code sample rules
+
+- Use Ruby examples only.
+- Use the official `mindee` gem.
+- Show requires explicitly.
+- Include the exact documented class and method names.
+- Use placeholders like `MY_API_KEY`, `MY_MODEL_ID`, and `/path/to/file.pdf`.
+- Keep samples focused on one task.
+
+## Preferred example topics
+
+### Client initialization
+Use:
+- `Mindee::V2::Client.new(api_key: 'MY_API_KEY')`
+- `Mindee::V2::Client.new` with `MINDEE_V2_API_KEY` env var
+
+### Input loading
+Use:
+- `Mindee::Input::Source::PathInputSource`
+- `Mindee::Input::Source::BytesInputSource`
+- `Mindee::Input::Source::Base64InputSource`
+- `Mindee::Input::Source::FileInputSource`
+- `Mindee::Input::Source::URLInputSource`
+
+### Sending documents
+Use:
+- `client.enqueue_and_get_result(...)` for polling
+- `client.enqueue(...)` for webhooks
+
+### Response handling
+Use:
+- `response.inference`
+- `response.raw_http`
+- `Mindee::Input::LocalResponse` for webhook payloads
+- HMAC signature validation via `local_response.valid_hmac_signature?(secret_key, signature)` when relevant
+
+### File preparation
+Use:
+- `input_source.page_count` — get number of pages
+- `input_source.compress!(...)` — compress before upload
+- `input_source.apply_page_options(options)` — trim or remove pages
+
+## Avoid
+
+- Direct REST examples
+- cURL examples
+- Manual authentication header construction
+- Bearer token examples for API keys
+- Non-Ruby examples
+- V1 examples unless the user explicitly asks for V1
+
+## If the user is unclear
+
+Ask for only what is needed:
+
+- input type: local file or URL
+- delivery pattern: polling or webhook
+- model ID
+- runtime context: Rails, Sinatra, background job, or script
+
+## Output style
+
+- Be concise.
+- Answer with runnable examples when code is requested.
+- Link to the most relevant doc section.
+- Do not overwhelm the user with every option.
+- Start with the documented default path.
+
+---
+
+# Agent Instructions: Querying The Documentation
+
+If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
+
+Perform an HTTP GET request on the documentation URL with the `ask` query parameter.
+Include `ruby+sdk+-+` at the beginning of the question to get answers specific to this library:
+
+```
+GET https://docs.mindee.com/integrations.md?ask=ruby+sdk+-+<question>
+```
+
+The question should be specific, self-contained, and written in natural language.
+The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
+
+Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.

data/bin/v2/parser.rb

@@ -141,7 +141,7 @@ module MindeeCLI
     # Initialize common options for search and product commands.
     # @param options_parser [OptionParser]
     def init_common_options(options_parser)
-      options_parser.on('-k [KEY]', '--key [KEY]', 'API key for the endpoint') { |v| @options[:api_key] = v }
+      options_parser.on('-k [KEY]', '--key [KEY]', 'Mindee V2 API key.') { |v| @options[:api_key] = v }
       options_parser.on('-o FORMAT', '--output-format FORMAT', ['raw', 'full', 'summary'],
                         'Format of the output (raw, full, summary). Default: summary') do |format|
         @options[:output_format] = format
@@ -179,6 +179,10 @@ module MindeeCLI
           options_parser.on('-a ALIAS', '--alias ALIAS', 'Add a file alias to the response') do |v|
             @options[:alias] = v
           end
+          options_parser.on('-w WEBHOOK_ID', '--webhook-id WEBHOOK_ID',
+                            'Specify a webhook by ID. May be used multiple times.') do |v|
+            (@options[:webhook_ids] ||= []) << v
+          end
           init_common_options(options_parser)
           options_parser.on('-F', '--fix-pdf', 'Attempt to repair PDF before enqueueing') do
             @options[:repair_pdf] = true
@@ -190,10 +194,10 @@ module MindeeCLI
     end
 
     # @return [Hash]
-    def setup_product_params
+    def setup_product_params(product_command)
       params = { model_id: @options[:model_id] }
       @options.each_pair do |key, value|
-        params[key] = value if V2_PRODUCTS['extraction'].include?(key)
+        params[key] = value if V2_PRODUCTS[product_command].include?(key) || %i[alias webhook_ids].include?(key)
       end
       params
     end
@@ -205,7 +209,7 @@ module MindeeCLI
       mindee_client = Mindee::V2::Client.new(api_key: options[:api_key])
       response_class = V2_PRODUCTS[product_command][:response_class]
       input_source = setup_input_source(options)
-      params = setup_product_params
+      params = setup_product_params(product_command)
 
       mindee_client.enqueue_and_get_result(
         response_class,

data/lib/mindee/image/extracted_image.rb

@@ -73,17 +73,10 @@ module Mindee
       # Return the file as a Mindee-compatible BufferInput source.
       #
       # @return [FileInputSource] A BufferInput source.
-      def as_source
+      def as_input_source
         @buffer.rewind
         Mindee::Input::Source::BytesInputSource.new(@buffer.read || '', @filename)
       end
-
-      # Return the file as a Mindee-compatible BufferInput source.
-      #
-      # @return [FileInputSource] A BufferInput source.
-      def as_input_source
-        as_source
-      end
     end
   end
 end

data/lib/mindee/image/extracted_images.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'extracted_image'
+
+module Mindee
+  # Image Extraction Module.
+  module Image
+    # List of extracted images.
+    class ExtractedImages < Array
+      # Save all extracted images to disk.
+      #
+      # @param output_path [String, Pathname] Directory path to save the extracted images to.
+      def save_all_to_disk(output_path)
+        each do |image|
+          image.write_to_file(File.join(output_path.to_s, image.filename))
+        end
+      end
+    end
+  end
+end

data/lib/mindee/image/image_extractor.rb

@@ -7,16 +7,17 @@ require 'stringio'
 require 'tempfile'
 require_relative '../input/sources'
 require_relative 'extracted_image'
+require_relative 'extracted_images'
 
 module Mindee
   # Image Extraction Module.
   module Image
     # Image Extraction wrapper class.
     module ImageExtractor
-      # Attaches an image as a new page in a PdfDocument object.
+      # Attaches an image as a new page in a PDFDocument object.
       #
       # @param [StringIO] input_buffer Input buffer. Only supports JPEG.
-      # @return [Origami::PDF] A PdfDocument handle.
+      # @return [Origami::PDF] A PDFDocument handle.
       def self.attach_image_as_new_file(input_buffer, format: 'jpg')
         magick_image = MiniMagick::Image.read(input_buffer)
         # NOTE: We force format consolidation to a single format to avoid frames being interpreted as the final output.
@@ -32,12 +33,12 @@ module Mindee
       # @param [Input::Source::LocalInputSource] input_source
       # @param [Integer] page_id ID of the Page to extract from.
       # @param [Array<Array<Geometry::Point>>, Array<Geometry::Quadrilateral>] polygons List of coordinates to extract.
-      # @return [Array<Image::ExtractedImage>] Extracted Images.
+      # @return [Image::ExtractedImages] Extracted Images.
       def self.extract_multiple_images_from_source(input_source, page_id, polygons)
         new_stream = load_input_source_pdf_page_as_stringio(input_source, page_id)
         new_stream.seek(0)
 
-        extract_images_from_polygons(input_source, page_id, polygons)
+        ExtractedImages.new(extract_images_from_polygons(input_source, page_id, polygons))
       end
 
       # Extracts images from their positions on a file (as polygons).
@@ -45,9 +46,9 @@ module Mindee
       # @param [Input::Source::LocalInputSource] input_source Local input source.
       # @param [Integer] page_id Page ID.
       # @param [Array<Geometry::Point, Geometry::Polygon, Geometry::Quadrilateral>] polygons
-      # @return [Array<Image::ExtractedImage>] Extracted Images.
+      # @return [Image::ExtractedImages] Extracted Images.
       def self.extract_images_from_polygons(input_source, page_id, polygons)
-        extracted_elements = [] # @type var extracted_elements: Array[Image::ExtractedImage]
+        extracted_elements = ExtractedImages.new # @type var extracted_elements: Image::ExtractedImages
 
         input_source.io_stream.rewind
         pdf_stream = StringIO.new(input_source.io_stream.read.to_s)
@@ -65,7 +66,7 @@ module Mindee
           min_max_x = Geometry.get_min_max_x(points)
           min_max_y = Geometry.get_min_max_y(points)
           file_extension = ImageUtils.determine_file_extension(input_source)
-          cropped_image = ImageUtils.crop_image(page_content, min_max_x, min_max_y)
+          cropped_image = crop_image(page_content, min_max_x, min_max_y)
           if file_extension == 'pdf'
             cropped_image.format('jpg')
           else
@@ -102,7 +103,7 @@ module Mindee
       #
       # @param input_file [LocalInputSource] Local input.
       # @param [Integer] page_id Page ID.
-      # @return [StringIO] A valid PdfDocument handle.
+      # @return [StringIO] A valid PDFDocument handle.
       def self.load_input_source_pdf_page_as_stringio(input_file, page_id)
         input_file.io_stream.rewind
         if input_file.pdf?
@@ -111,6 +112,23 @@ module Mindee
           input_file.io_stream
         end
       end
+
+      # Crops a MiniMagick Image from the given bounding box.
+      #
+      # @param [MiniMagick::Image] image Input Image.
+      # @param [Mindee::Geometry::MinMax] min_max_x minimum & maximum values for the x coordinates.
+      # @param [Mindee::Geometry::MinMax] min_max_y minimum & maximum values for the y coordinates.
+      def self.crop_image(image, min_max_x, min_max_y)
+        width = image[:width].to_i
+        height = image[:height].to_i
+
+        image.format('jpg')
+        new_width = (min_max_x.max - min_max_x.min) * width
+        new_height = (min_max_y.max - min_max_y.min) * height
+        image.crop("#{new_width}x#{new_height}+#{min_max_x.min * width}+#{min_max_y.min * height}")
+
+        image
+      end
     end
   end
 end

data/lib/mindee/image/image_utils.rb

@@ -124,23 +124,6 @@ module Mindee
         MiniMagick::Image.read(pdf_stream)
       end
 
-      # Crops a MiniMagick Image from a the given bounding box.
-      #
-      # @param [MiniMagick::Image] image Input Image.
-      # @param [Mindee::Geometry::MinMax] min_max_x minimum & maximum values for the x coordinates.
-      # @param [Mindee::Geometry::MinMax] min_max_y minimum & maximum values for the y coordinates.
-      def self.crop_image(image, min_max_x, min_max_y)
-        width = image[:width].to_i
-        height = image[:height].to_i
-
-        image.format('jpg')
-        new_width = (min_max_x.max - min_max_x.min) * width
-        new_height = (min_max_y.max - min_max_y.min) * height
-        image.crop("#{new_width}x#{new_height}+#{min_max_x.min * width}+#{min_max_y.min * height}")
-
-        image
-      end
-
       # Writes a MiniMagick::Image to a buffer.
       #
       # @param [MiniMagick::Image] image a valid MiniMagick image.

data/lib/mindee/image.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'image/extracted_image'
+require_relative 'image/extracted_images'
 require_relative 'image/image_compressor'
 require_relative 'image/image_extractor'
 require_relative 'image/image_utils'

data/lib/mindee/pdf/extracted_pdf.rb

@@ -3,7 +3,7 @@
 module Mindee
   # PDF Extraction Module.
   module PDF
-    # An extracted sub-Pdf.
+    # An extracted sub-PDF.
     class ExtractedPDF
       # Byte contents of the pdf
       # @return [StringIO]

data/lib/mindee/pdf/extracted_pdfs.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative 'extracted_pdf'
+
+module Mindee
+  # PDF Extraction Module.
+  module PDF
+    # List of extracted PDFs.
+    class ExtractedPDFs < Array
+      # Save all extracted PDFs to disk.
+      #
+      # @param output_path [String, Pathname] Directory path to save the extracted PDFs to.
+      def save_all_to_disk(output_path)
+        each do |pdf|
+          pdf.write_to_file(File.join(output_path.to_s, pdf.filename))
+        end
+      end
+    end
+  end
+end

data/lib/mindee/pdf/pdf_extractor.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 module Mindee
-  # Pdf Extraction Module.
+  # PDF Extraction Module.
   module PDF
-    # Pdf extraction class.
+    # PDF extraction class.
     class PDFExtractor
       # @param local_input [Mindee::Input::Source::LocalInputSource]
       def initialize(local_input)
@@ -23,15 +23,15 @@ module Mindee
         end
       end
 
-      # Retrieves the page count for the Pdf object.
+      # Retrieves the page count for the PDF object.
       # @return [Integer]
       def page_count
         Mindee::PDF::PDFProcessor.open_pdf(@source_pdf).pages.size
       end
 
-      # Creates a new Pdf from pages and save it into a buffer.
-      # @param page_indexes [Array<Integer>] List of page number to use for merging in the original Pdf.
-      # @return [StringIO] The buffer containing the new Pdf.
+      # Creates a new PDF from pages and save it into a buffer.
+      # @param page_indexes [Array<Integer>] List of page number to use for merging in the original PDF.
+      # @return [StringIO] The buffer containing the new PDF.
       def cut_pages(page_indexes)
         options = PageOptions.new(params: {
                                     page_indexes: page_indexes,
@@ -41,10 +41,10 @@ module Mindee
       end
 
       # Extract the sub-documents from the main pdf, based on the given list of page indexes.
-      # @param page_indexes [Array<Array<Integer>>] List of page number to use for merging in the original Pdf.
-      # @return [Array<Mindee::PDF::ExtractedPDF>] The buffer containing the new Pdf.
+      # @param page_indexes [Array<Array<Integer>>] List of page number to use for merging in the original PDF.
+      # @return [Mindee::PDF::ExtractedPDFs] The buffer containing the new PDF.
       def extract_sub_documents(page_indexes)
-        extracted_pdfs = [] # @type var extracted_pdfs: Array[Mindee::PDF::ExtractedPDF]
+        extracted_pdfs = ExtractedPDFs.new # @type var extracted_pdfs: Mindee::PDF::ExtractedPDFs
         extension = File.extname(@filename)
         basename = File.basename(@filename, extension)
         page_indexes.each do |page_index_list|
@@ -74,7 +74,7 @@ module Mindee
       # Extracts invoices as complete PDFs from the document.
       # @param page_indexes [Array<Array<Integer>, InvoiceSplitterV1InvoicePageGroup>]
       # @param strict [bool]
-      # @return [Array<Mindee::PDF::ExtractedPDF>]
+      # @return [Mindee::PDF::ExtractedPDFs]
       def extract_invoices(page_indexes, strict: false)
         raise Error::MindeePDFError, 'No indexes provided.' if page_indexes.empty?
 

data/lib/mindee/pdf.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative 'pdf/extracted_pdf'
+require_relative 'pdf/extracted_pdfs'
 require_relative 'pdf/pdf_compressor'
 require_relative 'pdf/pdf_extractor'
 require_relative 'pdf/pdf_processor'

data/lib/mindee/v2/file_operations/crop.rb

@@ -21,7 +21,7 @@ module Mindee
         #
         # @param input_source [LocalInputSource] Local Input Source to extract sub-receipts from.
         # @param crops [Array<CropItem>] List of crops.
-        # @return [CropFiles] Individual extracted zones as an array of ExtractedImage.
+        # @return [Image::ExtractedImages] Individual extracted zones as an array of ExtractedImage.
         # @raise [MindeeError] if the crops array is empty.
         def self.extract_crops(input_source, crops)
           if crops.nil? || crops.empty?
@@ -35,15 +35,16 @@ module Mindee
             polygons[crop.location.page] << crop.location.polygon
           end
 
-          images = [] # @type var images: Array[Image::ExtractedImage]
+          images = Mindee::Image::ExtractedImages.new
           polygons.each_with_index do |page_polygons, page_index|
-            extracted = Mindee::Image::ImageExtractor.extract_multiple_images_from_source(
-              input_source, page_index, page_polygons
+            images.concat(
+              Mindee::Image::ImageExtractor.extract_multiple_images_from_source(
+                input_source, page_index, page_polygons
+              )
             )
-            images.concat(extracted)
           end
 
-          CropFiles.new(images)
+          images
         end
       end
     end

data/lib/mindee/v2/file_operations/split.rb

@@ -18,7 +18,7 @@ module Mindee
         #
         # @param input_source [LocalInputSource] Input source to split.
         # @param splits [Array<Array<Integer>>] List of sub-lists of pages to keep.
-        # @return [SplitFiles] A list of extracted invoices.
+        # @return [PDF::ExtractedPDFs] A list of extracted invoices.
         # @raise [MindeeError] if no indexes are provided.
         def self.extract_splits(input_source, splits)
           raise Mindee::Error::MindeeError, 'No indexes provided.' if splits.nil? || splits.empty?
@@ -29,7 +29,7 @@ module Mindee
             (split[0]..split[1]).to_a
           end
 
-          SplitFiles.new(pdf_extractor.extract_sub_documents(page_groups))
+          pdf_extractor.extract_sub_documents(page_groups)
         end
       end
     end

data/lib/mindee/v2/file_operations.rb

@@ -1,6 +1,4 @@
 # frozen_string_literal: true
 
 require_relative 'file_operations/crop'
-require_relative 'file_operations/crop_files'
 require_relative 'file_operations/split'
-require_relative 'file_operations/split_files'

data/lib/mindee/v2/parsing/failed_inference_response.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Mindee
+  module V2
+    module Parsing
+      # "Webhook payload returned when an inference fails before producing a result.
+      class FailedInferenceResponse < Mindee::V2::Parsing::CommonResponse
+        # @return [String] UUID of the failed inference.
+        attr_reader :inference_id
+        # @return [String] UUID of the model used.
+        attr_reader :model_id
+        # @return [String] Name of the input file.
+        attr_reader :file_name
+        # @return [String, Nil] Alias sent for the file, if any.
+        attr_reader :file_alias
+        # @return [Mindee::V2::Parsing::ErrorResponse] Problem details for the failure, if available.
+        attr_reader :error
+        # @return [Time] Date and time when the inference was started.
+        attr_reader :created_at
+
+        def initialize(server_response)
+          super
+
+          @inference_id = server_response['inference_id']
+          @model_id = server_response['model_id']
+          @file_name = server_response['file_name']
+          @file_alias = server_response['file_alias']
+          @error = ErrorResponse.new(server_response['error'])
+          @created_at = Time.iso8601(server_response['created_at'])
+        end
+      end
+    end
+  end
+end

data/lib/mindee/v2/parsing.rb

@@ -14,3 +14,4 @@ require_relative 'parsing/rag_metadata'
 require_relative 'parsing/raw_text'
 require_relative 'parsing/raw_text_page'
 require_relative 'parsing/search'
+require_relative 'parsing/failed_inference_response'

data/lib/mindee/v2/product/crop/crop_item.rb

@@ -33,7 +33,7 @@ module Mindee
           #
           # @param input_source [Mindee::Input::Source::LocalInputSource] Local file to extract from
           # @return [ExtractedImage]
-          def extract_from_file(input_source)
+          def extract_from_input_source(input_source)
             Image::ImageExtractor.extract_multiple_images_from_source(
               input_source, @location.page, [@location.polygon]
             )[0]

data/lib/mindee/v2/product/crop/crop_response.rb

@@ -25,14 +25,6 @@ module Mindee
           def to_s
             @inference.to_s
           end
-
-          # Apply the crop inference to a file and return a list of extracted images.
-          #
-          # @param input_source [Mindee::Input::Source::LocalInputSource] Local file to extract from
-          # @return [FileOperation::CropFiles] List of extracted PDFs
-          def extract_from_file(input_source)
-            FileOperation::Crop.extract_crops(input_source, @inference.result.crops)
-          end
         end
       end
     end

data/lib/mindee/v2/product/crop/crop_result.rb

@@ -20,6 +20,14 @@ module Mindee
                      end
           end
 
+          # Apply the crop inference to a file and return a list of extracted images.
+          #
+          # @param input_source [Mindee::Input::Source::LocalInputSource] Local file to extract from
+          # @return [Image::ExtractedImages] List of extracted images
+          def extract_from_input_source(input_source)
+            FileOperation::Crop.extract_crops(input_source, @crops)
+          end
+
           # String representation.
           # @return [String]
           def to_s

data/lib/mindee/v2/product/split/split_range.rb

@@ -34,7 +34,7 @@ module Mindee
           #
           # @param input_source [Mindee::Input::Source::LocalInputSource] Local file to extract from
           # @return [PDF::ExtractedPDF]
-          def extract_from_file(input_source)
+          def extract_from_input_source(input_source)
             FileOperation::Split.extract_single_split(input_source, @page_range)
           end
         end

data/lib/mindee/v2/product/split/split_response.rb

@@ -25,14 +25,6 @@ module Mindee
           def to_s
             @inference.to_s
           end
-
-          # Splits the input PDF.
-          # @param input_source [Mindee::Input::Source::LocalInputSource] Path to the file or a File object.
-          # @return [FileOperation::SplitFiles]
-          def extract_from_file(input_source)
-            splits = @inference.result.splits.map(&:page_range)
-            FileOperation::Split.extract_splits(input_source, splits)
-          end
         end
       end
     end

data/lib/mindee/v2/product/split/split_result.rb

@@ -20,6 +20,13 @@ module Mindee
                       end
           end
 
+          # Splits the input PDF.
+          # @param input_source [Mindee::Input::Source::LocalInputSource] Path to the file or a File object.
+          # @return [PDF::ExtractedPDFs]
+          def extract_from_input_source(input_source)
+            FileOperation::Split.extract_splits(input_source, splits.map(&:page_range))
+          end
+
           # String representation.
           # @return [String]
           def to_s

data/lib/mindee/version.rb

@@ -3,7 +3,7 @@
 # Mindee
 module Mindee
   # Current version.
-  VERSION = '5.2.2'
+  VERSION = '5.3.0'
 
   # Finds and return the current platform.
   # @return [Symbol, Hash[String | Symbol, Regexp], Nil?]

data/sig/mindee/image/extracted_image.rbs

@@ -14,7 +14,6 @@ module Mindee
         ?preserve_input_filename: bool
       ) -> Integer
       def write_to_file: (String, ?String?) -> void
-      def as_source: -> Input::Source::BytesInputSource
       def as_input_source: -> Input::Source::BytesInputSource
     end
   end

data/sig/mindee/image/extracted_images.rbs

@@ -0,0 +1,8 @@
+# lib/mindee/image/extracted_images.rb
+module Mindee
+  module Image
+    class ExtractedImages < Array[ExtractedImage]
+      def save_all_to_disk: (String | Pathname) -> void
+    end
+  end
+end

data/sig/mindee/image/image_extractor.rbs

@@ -4,9 +4,10 @@ module Mindee
     module ImageExtractor
       def self.attach_image_as_new_file: (StringIO | File, ?format: String) -> Origami::PDF
       def self.to_blob: () -> String
-      def self.extract_multiple_images_from_source: (Input::Source::LocalInputSource, Integer, Array[Array[Geometry::Point] |Geometry::Polygon | Geometry::Quadrilateral]) -> Array[ExtractedImage]
-      def self.extract_images_from_polygons: (Input::Source::LocalInputSource, Integer, Array[Array[Geometry::Point] | Geometry::Polygon | Geometry::Quadrilateral]) -> Array[ExtractedImage]
+      def self.extract_multiple_images_from_source: (Input::Source::LocalInputSource, Integer, Array[Array[Geometry::Point] |Geometry::Polygon | Geometry::Quadrilateral]) -> ExtractedImages
+      def self.extract_images_from_polygons: (Input::Source::LocalInputSource, Integer, Array[Array[Geometry::Point] | Geometry::Polygon | Geometry::Quadrilateral]) -> ExtractedImages
       def self.create_extracted_image: (StringIO | File, String, Integer, Integer) -> ExtractedImage
+      def self.crop_image: (MiniMagick::Image, Geometry::MinMax, Geometry::MinMax) -> (MiniMagick::Image)
       def self.load_input_source_pdf_page_as_stringio: (Input::Source::LocalInputSource, Integer) -> (StringIO | File)
     end
   end

data/sig/mindee/image/image_utils.rbs

@@ -11,7 +11,6 @@ module Mindee
       def self.pdf_to_magick_image: (StringIO | File, Integer) -> MiniMagick::Image
       def self.normalize_polygon: (Geometry::Quadrilateral | Geometry::Polygon | Array[Geometry::Point]) -> Geometry::Quadrilateral
       def self.read_page_content: (StringIO | File) -> (MiniMagick::Image)
-      def self.crop_image: (MiniMagick::Image, Geometry::MinMax, Geometry::MinMax) -> (MiniMagick::Image)
       def self.write_image_to_buffer: (MiniMagick::Image, StringIO) -> void
       def self.determine_file_extension: (Input::Source::LocalInputSource) -> String?
     end

data/sig/mindee/pdf/extracted_pdfs.rbs

@@ -0,0 +1,8 @@
+# lib/mindee/pdf/extracted_pdfs.rb
+module Mindee
+  module PDF
+    class ExtractedPDFs < Array[ExtractedPDF]
+      def save_all_to_disk: (String | Pathname) -> void
+    end
+  end
+end

data/sig/mindee/pdf/pdf_extractor.rbs

@@ -11,9 +11,9 @@ module Mindee
 
       def cut_pages: (Array[Integer]) -> StringIO
 
-      def extract_sub_documents: (Array[Array[Integer]]) -> Array[ExtractedPDF]
+      def extract_sub_documents: (Array[Array[Integer]]) -> ExtractedPDFs
 
-      def extract_invoices: (Array[Mindee::V1::Product::InvoiceSplitter::InvoiceSplitterV1InvoicePageGroup] | Array[Array[Integer]], ?strict: bool) -> Array[ExtractedPDF]
+      def extract_invoices: (Array[Mindee::V1::Product::InvoiceSplitter::InvoiceSplitterV1InvoicePageGroup] | Array[Array[Integer]], ?strict: bool) -> ExtractedPDFs
     end
   end
 end

data/sig/mindee/v2/file_operation/crop.rbs

@@ -3,7 +3,7 @@ module Mindee
     module FileOperation
       module Crop
         def self.extract_single_crop: (Input::Source::LocalInputSource, Parsing::Field::FieldLocation) -> Image::ExtractedImage
-        def self.extract_crops: (Input::Source::LocalInputSource, Array[Product::Crop::CropItem]) -> CropFiles
+        def self.extract_crops: (Input::Source::LocalInputSource, Array[Product::Crop::CropItem]) -> Image::ExtractedImages
       end
     end
   end

data/sig/mindee/v2/file_operation/split.rbs

@@ -4,7 +4,7 @@ module Mindee
       module Split
         def self.extract_single_split: (Input::Source::LocalInputSource, Array[Integer]) -> PDF::ExtractedPDF
 
-        def self.extract_splits: (Input::Source::LocalInputSource, Array[Array[Integer]]) -> SplitFiles
+        def self.extract_splits: (Input::Source::LocalInputSource, Array[Array[Integer]]) -> PDF::ExtractedPDFs
       end
     end
   end

data/sig/mindee/v2/parsing/failed_inference_response.rbs

@@ -0,0 +1,15 @@
+module Mindee
+  module V2
+    module Parsing
+      class FailedInferenceResponse
+        def initialize: (Hash[String | Symbol, untyped]) -> void
+        attr_reader created_at: Time
+        attr_reader error: ::Mindee::V2::Parsing::ErrorResponse
+        attr_reader file_alias: String
+        attr_reader file_name: String
+        attr_reader inference_id: String
+        attr_reader model_id: String
+      end
+    end
+  end
+end

data/sig/mindee/v2/product/crop/crop_item.rbs

@@ -9,7 +9,7 @@ module Mindee
 
           def initialize: (Hash[String | Symbol, untyped]) -> void
 
-          def extract_from_file: (Input::Source::LocalInputSource) -> Image::ExtractedImage
+          def extract_from_input_source: (Input::Source::LocalInputSource) -> Image::ExtractedImage
 
           def to_s: -> String
         end

data/sig/mindee/v2/product/crop/crop_response.rbs

@@ -13,8 +13,6 @@ module Mindee
 
           def _params_type: -> singleton(Params::CropParameters)
 
-          def extract_from_file: (Input::Source::LocalInputSource) -> FileOperation::CropFiles
-
           def to_s: -> String
           def self._params_type: () -> singleton(Params::CropParameters)
           def self.slug: () -> String

data/sig/mindee/v2/product/crop/crop_result.rbs

@@ -6,6 +6,7 @@ module Mindee
           attr_reader crops: Array[CropItem]
 
           def initialize: (Hash[String | Symbol, untyped]) -> void
+          def extract_from_input_source: (Input::Source::LocalInputSource) -> Image::ExtractedImages
           def to_s: -> String
         end
       end

data/sig/mindee/v2/product/split/split_range.rbs

@@ -9,7 +9,7 @@ module Mindee
 
           def initialize: (Hash[String | Symbol, untyped]) -> void
 
-          def extract_from_file: (Input::Source::LocalInputSource) -> PDF::ExtractedPDF
+          def extract_from_input_source: (Input::Source::LocalInputSource) -> PDF::ExtractedPDF
 
           def to_s: -> String
         end

data/sig/mindee/v2/product/split/split_response.rbs

@@ -13,8 +13,6 @@ module Mindee
 
           def _params_type: -> singleton(Params::SplitParameters)
 
-          def extract_from_file: (Mindee::Input::Source::LocalInputSource) -> FileOperation::SplitFiles
-
           def to_s: -> String
           def self._params_type: () -> singleton(Params::SplitParameters)
           def self.slug: () -> String

data/sig/mindee/v2/product/split/split_result.rbs

@@ -5,7 +5,10 @@ module Mindee
         class SplitResult
           attr_reader splits: Array[SplitRange]
 
+          def extract_from_input_source: (Mindee::Input::Source::LocalInputSource) -> PDF::ExtractedPDFs
+
           def initialize: (Hash[String | Symbol, untyped]) -> void
+
           def to_s: -> String
         end
       end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mindee
 version: !ruby/object:Gem::Version
-  version: 5.2.2
+  version: 5.3.0
 platform: ruby
 authors:
 - Mindee, SA
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-18 00:00:00.000000000 Z
+date: 2026-07-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -193,6 +193,7 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- SKILL.md
 - Steepfile
 - bin/console
 - bin/mindee.rb
@@ -250,6 +251,7 @@ files:
 - lib/mindee/http/response_validation.rb
 - lib/mindee/image.rb
 - lib/mindee/image/extracted_image.rb
+- lib/mindee/image/extracted_images.rb
 - lib/mindee/image/image_compressor.rb
 - lib/mindee/image/image_extractor.rb
 - lib/mindee/image/image_utils.rb
@@ -269,6 +271,7 @@ files:
 - lib/mindee/page_options.rb
 - lib/mindee/pdf.rb
 - lib/mindee/pdf/extracted_pdf.rb
+- lib/mindee/pdf/extracted_pdfs.rb
 - lib/mindee/pdf/pdf_compressor.rb
 - lib/mindee/pdf/pdf_extractor.rb
 - lib/mindee/pdf/pdf_processor.rb
@@ -398,9 +401,7 @@ files:
 - lib/mindee/v2/client.rb
 - lib/mindee/v2/file_operations.rb
 - lib/mindee/v2/file_operations/crop.rb
-- lib/mindee/v2/file_operations/crop_files.rb
 - lib/mindee/v2/file_operations/split.rb
-- lib/mindee/v2/file_operations/split_files.rb
 - lib/mindee/v2/http.rb
 - lib/mindee/v2/http/.rubocop.yml
 - lib/mindee/v2/http/api_v2_settings.rb
@@ -411,6 +412,7 @@ files:
 - lib/mindee/v2/parsing/common_response.rb
 - lib/mindee/v2/parsing/error_item.rb
 - lib/mindee/v2/parsing/error_response.rb
+- lib/mindee/v2/parsing/failed_inference_response.rb
 - lib/mindee/v2/parsing/field.rb
 - lib/mindee/v2/parsing/field/base_field.rb
 - lib/mindee/v2/parsing/field/field_confidence.rb
@@ -492,6 +494,7 @@ files:
 - sig/mindee/http/http_error_handler.rbs
 - sig/mindee/http/response_validation.rbs
 - sig/mindee/image/extracted_image.rbs
+- sig/mindee/image/extracted_images.rbs
 - sig/mindee/image/image_compressor.rbs
 - sig/mindee/image/image_extractor.rbs
 - sig/mindee/image/image_utils.rbs
@@ -507,6 +510,7 @@ files:
 - sig/mindee/logging/logger.rbs
 - sig/mindee/page_options.rbs
 - sig/mindee/pdf/extracted_pdf.rbs
+- sig/mindee/pdf/extracted_pdfs.rbs
 - sig/mindee/pdf/pdf_compressor.rbs
 - sig/mindee/pdf/pdf_extractor.rbs
 - sig/mindee/pdf/pdf_processor.rbs
@@ -622,9 +626,7 @@ files:
 - sig/mindee/v1/product/universal/universal_prediction.rbs
 - sig/mindee/v2/client.rbs
 - sig/mindee/v2/file_operation/crop.rbs
-- sig/mindee/v2/file_operation/crop_files.rbs
 - sig/mindee/v2/file_operation/split.rbs
-- sig/mindee/v2/file_operation/split_files.rbs
 - sig/mindee/v2/http/api_v2_settings.rbs
 - sig/mindee/v2/http/mindee_api_v2.rbs
 - sig/mindee/v2/parsing/base_inference.rbs
@@ -632,6 +634,7 @@ files:
 - sig/mindee/v2/parsing/common_response.rbs
 - sig/mindee/v2/parsing/error_item.rbs
 - sig/mindee/v2/parsing/error_response.rbs
+- sig/mindee/v2/parsing/failed_inference_response.rbs
 - sig/mindee/v2/parsing/field/base_field.rbs
 - sig/mindee/v2/parsing/field/field_confidence.rbs
 - sig/mindee/v2/parsing/field/field_location.rbs

data/lib/mindee/v2/file_operations/crop_files.rb

@@ -1,25 +0,0 @@
-# frozen_string_literal: true
-
-module Mindee
-  module V2
-    module FileOperation
-      # Collection of cropped files.
-      class CropFiles < Array
-        # Save all extracted crops to disk.
-        #
-        # @param path [String, Pathname] Path to save the extracted crops to.
-        # @param prefix [String] Prefix to add to the filename, defaults to 'crop'.
-        # @param file_format [String, nil] File format to save the crops as, defaults to jpg if nil.]
-        def save_all_to_disk(path, prefix: 'crop', file_format: nil)
-          FileUtils.mkdir_p(path)
-          each.with_index(1) do |crop, idx|
-            filename = "#{prefix}_#{format('%03d', idx)}.jpg"
-            file_path = File.join(path.to_s, filename)
-
-            crop.write_to_file(file_path, file_format)
-          end
-        end
-      end
-    end
-  end
-end

data/lib/mindee/v2/file_operations/split_files.rb

@@ -1,25 +0,0 @@
-# frozen_string_literal: true
-
-module Mindee
-  module V2
-    module FileOperation
-      # Collection of split files.
-      class SplitFiles < Array
-        # Save all extracted splits to disk.
-        #
-        # @param path [String, Pathname] Path to save the extracted splits to.
-        # @param prefix [String] Prefix to add to the filename, defaults to 'split'.
-        def save_all_to_disk(path, prefix: 'split')
-          FileUtils.mkdir_p(path)
-
-          each.with_index(1) do |split, idx|
-            filename = "#{prefix}_#{format('%03d', idx)}.pdf"
-            file_path = File.join(path.to_s, filename)
-
-            split.write_to_file(file_path)
-          end
-        end
-      end
-    end
-  end
-end

data/sig/mindee/v2/file_operation/crop_files.rbs

@@ -1,9 +0,0 @@
-module Mindee
-  module V2
-    module FileOperation
-      class CropFiles < Array[Image::ExtractedImage]
-        def save_all_to_disk: (String | Pathname, ?prefix: String, ?file_format: String?) -> void
-      end
-    end
-  end
-end

data/sig/mindee/v2/file_operation/split_files.rbs

@@ -1,9 +0,0 @@
-module Mindee
-  module V2
-    module FileOperation
-      class SplitFiles < Array[PDF::ExtractedPDF]
-        def save_all_to_disk: (String | Pathname, ?prefix: String?) -> void
-      end
-    end
-  end
-end