kreuzberg 4.2.0 → 4.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a1c9adffca7d75c142bd661f1d481b1aee00d97c6f62dcc70292f37978bcc17
-  data.tar.gz: 227af2ed45bff1dfa9afebd69220d15a41b2e476bf97f8a83173d21aab8b88e1
+  metadata.gz: '010412940492f83bc170a4a4efc644ac7e3818502734035523796287837a3893'
+  data.tar.gz: af24cba007cc58283d678d4b15251ebae3a5740f60ade9a54cc19973a2022a82
 SHA512:
-  metadata.gz: 0d1b0081f89a73f5422e68a714fc415f6d290dd8be7cf0ba6d454cfdf1938ebdac4919358b25d6e5a0bc1a209e1b165062a0341d28cde1b3fa0595bffec837f5
-  data.tar.gz: fc5a5f29309c29fbbf63ba035cf5e462e78b15c2afc239fb333bd8b6e70ef061219822ed4d533f81bb35cdd62db84da8c01e8f172561b0f7fb802b848b491c0a
+  metadata.gz: ad67348bec54a01ca3592ed72e9b2b8bc9e711a37e11b40ada31466c67f834132fc0de278c53a1c014fa6751da7abebae934cff2a9cc1835f7e056c895a273cb
+  data.tar.gz: ca2cdb076a5d1af67f0e807978a966d1a391cc286bcdf5499544e3403196140918a54674beab77ea09fc0e8bc7ab66f357da5d984326a511b1d21643a3d6cf41

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    kreuzberg (4.2.0)
+    kreuzberg (4.2.1)
 
 GEM
   remote: https://rubygems.org/
@@ -207,7 +207,7 @@ CHECKSUMS
   i18n (1.14.8) sha256=285778639134865c5e0f6269e0b818256017e8cde89993fdfcbfb64d088824a5
   io-console (0.8.2) sha256=d6e3ae7a7cc7574f4b8893b4fca2162e57a825b223a177b7afa236c5ef9814cc
   json (2.18.0) sha256=b10506aee4183f5cf49e0efc48073d7b75843ce3782c68dbeb763351c08fd505
-  kreuzberg (4.2.0)
+  kreuzberg (4.2.1)
   language_server-protocol (3.17.0.5) sha256=fd1e39a51a28bf3eec959379985a72e296e9f9acfce46f6a79d31ca8760803cc
   lint_roller (1.1.0) sha256=2c0c845b632a7d172cb849cc90c1bce937a28c5c8ccccb50dfd46a485003cc87
   listen (3.10.0) sha256=c6e182db62143aeccc2e1960033bebe7445309c7272061979bb098d03760c9d2

data/README.md

@@ -22,7 +22,7 @@
     <img src="https://img.shields.io/maven-central/v/dev.kreuzberg/kreuzberg?label=Java&color=007ec6" alt="Java">
   </a>
   <a href="https://github.com/kreuzberg-dev/kreuzberg/releases">
-    <img src="https://img.shields.io/github/v/tag/kreuzberg-dev/kreuzberg?label=Go&color=007ec6&filter=v4.2.0" alt="Go">
+    <img src="https://img.shields.io/github/v/tag/kreuzberg-dev/kreuzberg?label=Go&color=007ec6&filter=v4.2.1" alt="Go">
   </a>
   <a href="https://www.nuget.org/packages/Kreuzberg/">
     <img src="https://img.shields.io/nuget/v/Kreuzberg?label=C%23&color=007ec6" alt="C#">

data/ext/kreuzberg_rb/native/Cargo.lock

@@ -716,9 +716,9 @@ dependencies = [
 
 [[package]]
 name = "cc"
-version = "1.2.53"
+version = "1.2.54"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "755d2fce177175ffca841e9a06afdb2c4ab0f593d53b4dee48147dfaade85932"
+checksum = "6354c81bbfd62d9cfa9cb3c773c2b7b2a3a482d569de977fd0e961f6e7c00583"
 dependencies = [
  "find-msvc-tools",
  "jobserver",
@@ -2027,9 +2027,9 @@ dependencies = [
 
 [[package]]
 name = "html-to-markdown-rs"
-version = "2.23.1"
+version = "2.23.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e1f4d6781ac8dd203853803d27054ca4153c7fd0f3956cb7fc95dc06f42a1c46"
+checksum = "ffbf49450676163bdf69fac2acf72674fcf2d2aaf690aa247368c567cc9afb2a"
 dependencies = [
  "astral-tl",
  "base64 0.22.1",
@@ -2627,7 +2627,7 @@ dependencies = [
 
 [[package]]
 name = "kreuzberg"
-version = "4.1.0"
+version = "4.2.0"
 dependencies = [
  "ahash",
  "async-trait",
@@ -2706,17 +2706,18 @@ dependencies = [
  "uuid",
  "whatlang",
  "yake-rust",
- "zip 7.1.0",
+ "zip 7.2.0",
 ]
 
 [[package]]
 name = "kreuzberg-ffi"
-version = "4.1.0"
+version = "4.2.0"
 dependencies = [
  "async-trait",
  "cbindgen",
  "html-to-markdown-rs",
  "kreuzberg",
+ "log",
  "serde",
  "serde_json",
  "tokio",
@@ -2767,14 +2768,14 @@ dependencies = [
 
 [[package]]
 name = "kreuzberg-tesseract"
-version = "4.1.0"
+version = "4.2.0"
 dependencies = [
  "cc",
  "cmake",
  "libc",
  "reqwest 0.13.1",
  "thiserror 2.0.18",
- "zip 7.1.0",
+ "zip 7.2.0",
 ]
 
 [[package]]
@@ -5022,9 +5023,9 @@ dependencies = [
 
 [[package]]
 name = "rmcp"
-version = "0.13.0"
+version = "0.14.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d1815dbc06c414d720f8bc1951eccd66bc99efc6376331f1e7093a119b3eb508"
+checksum = "0a621b37a548ff6ab6292d57841eb25785a7f146d89391a19c9f199414bd13da"
 dependencies = [
  "async-trait",
  "axum",
@@ -5054,9 +5055,9 @@ dependencies = [
 
 [[package]]
 name = "rmcp-macros"
-version = "0.13.0"
+version = "0.14.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "11f0bc7008fa102e771a76c6d2c9b253be3f2baa5964e060464d038ae1cbc573"
+checksum = "6b79ed92303f9262db79575aa8c3652581668e9d136be6fd0b9ededa78954c95"
 dependencies = [
  "darling 0.23.0",
  "proc-macro2",
@@ -6013,6 +6014,7 @@ checksum = "91e7d9e3bb61134e77bde20dd4825b97c010155709965fedf0f49bb138e52a9d"
 dependencies = [
  "deranged",
  "itoa",
+ "js-sys",
  "num-conv",
  "powerfmt",
  "serde",
@@ -6405,6 +6407,12 @@ version = "0.25.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d2df906b07856748fa3f6e0ad0cbaa047052d4a7dd609e231c4f72cee8c36f31"
 
+[[package]]
+name = "typed-path"
+version = "0.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e43ffa54726cdc9ea78392023ffe9fe9cf9ac779e1c6fcb0d23f9862e3879d20"
+
 [[package]]
 name = "typeid"
 version = "1.0.3"
@@ -6698,9 +6706,9 @@ checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
 
 [[package]]
 name = "uuid"
-version = "1.19.0"
+version = "1.20.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e2e054861b4bd027cd373e18e8d8d8e6548085000e41290d95ce0c373a654b4a"
+checksum = "ee48d38b119b0cd71fe4141b30f5ba9c7c5d9f4e7a3a8b4a674e4b6ef789976f"
 dependencies = [
  "getrandom 0.3.4",
  "js-sys",
@@ -7498,9 +7506,9 @@ dependencies = [
 
 [[package]]
 name = "zip"
-version = "7.1.0"
+version = "7.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9013f1222db8a6d680f13a7ccdc60a781199cd09c2fa4eff58e728bb181757fc"
+checksum = "c42e33efc22a0650c311c2ef19115ce232583abbe80850bc8b66509ebef02de0"
 dependencies = [
  "aes",
  "bzip2",
@@ -7518,6 +7526,7 @@ dependencies = [
  "ppmd-rust",
  "sha1",
  "time",
+ "typed-path",
  "zeroize",
  "zopfli",
  "zstd",

data/lib/kreuzberg/cli.rb

@@ -8,24 +8,34 @@ module Kreuzberg
 
     # Extract content from a file using the CLI
     #
-    # @param path [String] Path to the file
+    # @param path_or_nil [String, nil] Path to the file (positional, for backward compatibility)
+    # @param path [String] Path to the file (keyword argument)
     # @param output [String] Output format ("text", "json", "markdown")
     # @param ocr [Boolean] Enable OCR
     # @return [String] Extracted content
     #
-    def extract(path, output: 'text', ocr: false)
-      args = ['extract', path, '--format', output]
+    def extract(path_or_nil = nil, path: nil, output: 'text', ocr: false)
+      # Support both positional and keyword argument for path (backward compatibility)
+      actual_path = path_or_nil || path
+      raise ArgumentError, 'path is required' if actual_path.nil?
+
+      args = ['extract', actual_path, '--format', output]
       args.push('--ocr', ocr ? 'true' : 'false')
       CLIProxy.call(args)
     end
 
     # Detect MIME type of a file using the CLI
     #
-    # @param path [String] Path to the file
+    # @param path_or_nil [String, nil] Path to the file (positional, for backward compatibility)
+    # @param path [String] Path to the file (keyword argument)
     # @return [String] MIME type
     #
-    def detect(path)
-      CLIProxy.call(['detect', path]).strip
+    def detect(path_or_nil = nil, path: nil)
+      # Support both positional and keyword argument for path (backward compatibility)
+      actual_path = path_or_nil || path
+      raise ArgumentError, 'path is required' if actual_path.nil?
+
+      CLIProxy.call(['detect', actual_path]).strip
     end
 
     # Get CLI version

data/lib/kreuzberg/cli_proxy.rb

@@ -91,11 +91,13 @@ module Kreuzberg
         lib_path.join('bin', binary_name),
         lib_path.join(binary_name),
         root_path.join('../../crates/kreuzberg-cli/target/release', binary_name),
-        root_path.join('../../target/release', binary_name)
+        root_path.join('../../target/release', binary_name),
+        root_path.join('../../target/debug', binary_name)
       ]
 
       workspace_root = root_path.parent&.parent
       paths << workspace_root.join('target', 'release', binary_name) if workspace_root
+      paths << workspace_root.join('target', 'debug', binary_name) if workspace_root
 
       paths
     end

data/lib/kreuzberg/config.rb

@@ -715,10 +715,13 @@ module Kreuzberg
     class Extraction
       attr_reader :use_cache, :enable_quality_processing, :force_ocr,
                   :ocr, :chunking, :language_detection, :pdf_options,
-                  :image_extraction, :image_preprocessing, :postprocessor,
+                  :images, :image_preprocessing, :postprocessor,
                   :token_reduction, :keywords, :html_options, :pages,
                   :max_concurrent_extractions, :output_format, :result_format
 
+      # Alias for backward compatibility - image_extraction is the canonical name
+      alias image_extraction images
+
       # Load configuration from a file.
       #
       # Detects the file format from the extension (.toml, .yaml, .json)
@@ -746,6 +749,12 @@ module Kreuzberg
         images: :image_extraction
       }.freeze
 
+      # Valid output format values (case-insensitive, normalized internally)
+      VALID_OUTPUT_FORMATS = %w[plain markdown html djot].freeze
+
+      # Valid result format values (case-insensitive, normalized internally)
+      VALID_RESULT_FORMATS = %w[unified elements element_based].freeze
+
       def self.from_file(path)
         hash = Kreuzberg._config_from_file_native(path)
         new(**normalize_hash_keys(hash))
@@ -836,7 +845,7 @@ module Kreuzberg
         @chunking = normalize_config(params[:chunking], Chunking)
         @language_detection = normalize_config(params[:language_detection], LanguageDetection)
         @pdf_options = normalize_config(params[:pdf_options], PDF)
-        @image_extraction = normalize_config(params[:image_extraction], ImageExtraction)
+        @images = normalize_config(params[:image_extraction], ImageExtraction)
         @image_preprocessing = normalize_config(params[:image_preprocessing], ImagePreprocessing)
         @postprocessor = normalize_config(params[:postprocessor], PostProcessor)
         @token_reduction = normalize_config(params[:token_reduction], TokenReduction)
@@ -844,8 +853,28 @@ module Kreuzberg
         @html_options = normalize_config(params[:html_options], HtmlOptions)
         @pages = normalize_config(params[:pages], PageConfig)
         @max_concurrent_extractions = params[:max_concurrent_extractions]&.to_i
-        @output_format = params[:output_format]&.to_s
-        @result_format = params[:result_format]&.to_s
+        @output_format = validate_output_format(params[:output_format])
+        @result_format = validate_result_format(params[:result_format])
+      end
+
+      def validate_output_format(value)
+        return nil if value.nil?
+
+        str_value = value.to_s.downcase
+        return str_value if VALID_OUTPUT_FORMATS.include?(str_value)
+
+        raise ArgumentError,
+              "Invalid output_format: #{value}. Valid values: #{VALID_OUTPUT_FORMATS.join(', ')}"
+      end
+
+      def validate_result_format(value)
+        return nil if value.nil?
+
+        str_value = value.to_s.downcase
+        return str_value if VALID_RESULT_FORMATS.include?(str_value)
+
+        raise ArgumentError,
+              "Invalid result_format: #{value}. Valid values: #{VALID_RESULT_FORMATS.join(', ')}"
       end
 
       # rubocop:disable Metrics/CyclomaticComplexity
@@ -859,7 +888,7 @@ module Kreuzberg
           chunking: @chunking&.to_h,
           language_detection: @language_detection&.to_h,
           pdf_options: @pdf_options&.to_h,
-          image_extraction: @image_extraction&.to_h,
+          images: @images&.to_h,
           image_preprocessing: @image_preprocessing&.to_h,
           postprocessor: @postprocessor&.to_h,
           token_reduction: @token_reduction&.to_h,
@@ -995,7 +1024,7 @@ module Kreuzberg
         when :pdf_options
           @pdf_options = normalize_config(value, PDF)
         when :image_extraction
-          @image_extraction = normalize_config(value, ImageExtraction)
+          @images = normalize_config(value, ImageExtraction)
         when :image_preprocessing
           @image_preprocessing = normalize_config(value, ImagePreprocessing)
         when :postprocessor
@@ -1011,9 +1040,9 @@ module Kreuzberg
         when :max_concurrent_extractions
           @max_concurrent_extractions = value&.to_i
         when :output_format
-          @output_format = value&.to_s
+          @output_format = validate_output_format(value)
         when :result_format
-          @result_format = value&.to_s
+          @result_format = validate_result_format(value)
         else
           raise ArgumentError, "Unknown configuration key: #{key}"
         end
@@ -1035,6 +1064,24 @@ module Kreuzberg
         nil
       end
 
+      # Set output_format attribute
+      #
+      # @param value [String, nil] Output format value
+      # @return [String, nil] The value that was set
+      #
+      def output_format=(value)
+        @output_format = validate_output_format(value)
+      end
+
+      # Set result_format attribute
+      #
+      # @param value [String, nil] Result format value
+      # @return [String, nil] The value that was set
+      #
+      def result_format=(value)
+        @result_format = validate_result_format(value)
+      end
+
       private
 
       def normalize_config(value, klass)
@@ -1053,7 +1100,7 @@ module Kreuzberg
         @chunking = merged.chunking
         @language_detection = merged.language_detection
         @pdf_options = merged.pdf_options
-        @image_extraction = merged.image_extraction
+        @images = merged.image_extraction
         @image_preprocessing = merged.image_preprocessing
         @postprocessor = merged.postprocessor
         @token_reduction = merged.token_reduction

data/lib/kreuzberg/djot_content.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+begin
+  require 'json'
+rescue LoadError
+  require 'json/pure'
+end
+
+module Kreuzberg
+  class Result
+    # Djot structured content representation
+    #
+    # Represents document content in Djot format with structured metadata about
+    # blocks, images, links, footnotes, and other document elements.
+    #
+    class DjotContent
+      attr_reader :plain_text, :blocks, :metadata_json, :tables, :images, :links, :footnotes, :attributes
+
+      # Represents a formatted block in Djot content
+      class FormattedBlock
+        attr_reader :block_type, :children, :attributes, :content, :level
+
+        # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+        def initialize(hash_or_type = nil, children: nil, attributes: nil, content: nil, level: nil, block_type: nil)
+          if hash_or_type.is_a?(Hash)
+            # Initialize from hash
+            @block_type = hash_or_type[:block_type] || hash_or_type['block_type'] || ''
+            @children = hash_or_type[:children] || hash_or_type['children']
+            @attributes = hash_or_type[:attributes] || hash_or_type['attributes'] || {}
+            @content = hash_or_type[:content] || hash_or_type['content']
+            @level = hash_or_type[:level] || hash_or_type['level']
+          else
+            # Initialize from keyword arguments (for backward compatibility)
+            @block_type = block_type || hash_or_type || ''
+            @children = children || []
+            @attributes = attributes || {}
+            @content = content
+            @level = level
+          end
+        end
+        # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+        def to_h
+          {
+            block_type: @block_type,
+            children: @children,
+            attributes: @attributes,
+            content: @content,
+            level: @level
+          }.compact
+        end
+      end
+
+      # Represents an image in Djot content
+      class DjotImage
+        attr_reader :url, :alt, :title, :width, :height
+        alias src url
+
+        # rubocop:disable Metrics/CyclomaticComplexity
+        def initialize(hash_or_url = nil, alt: nil, title: nil, width: nil, height: nil, url: nil, src: nil)
+          if hash_or_url.is_a?(Hash)
+            # Initialize from hash (supports both 'url' and 'src' keys)
+            @url = hash_or_url[:url] || hash_or_url['url'] || hash_or_url[:src] || hash_or_url['src']
+            @alt = hash_or_url[:alt] || hash_or_url['alt']
+            @title = hash_or_url[:title] || hash_or_url['title']
+            @width = hash_or_url[:width] || hash_or_url['width']
+            @height = hash_or_url[:height] || hash_or_url['height']
+          else
+            # Initialize from keyword arguments
+            @url = url || src || hash_or_url
+            @alt = alt
+            @title = title
+            @width = width
+            @height = height
+          end
+        end
+        # rubocop:enable Metrics/CyclomaticComplexity
+
+        def to_h
+          {
+            url: @url,
+            alt: @alt,
+            title: @title,
+            width: @width,
+            height: @height
+          }.compact
+        end
+      end
+
+      # Represents a link in Djot content
+      class DjotLink
+        attr_reader :url, :text, :title, :link_type
+        alias href url
+
+        # rubocop:disable Metrics/CyclomaticComplexity
+        def initialize(hash_or_url = nil, text: nil, title: nil, url: nil, href: nil, link_type: nil)
+          if hash_or_url.is_a?(Hash)
+            # Initialize from hash (supports both 'url' and 'href' keys)
+            @url = hash_or_url[:url] || hash_or_url['url'] || hash_or_url[:href] || hash_or_url['href']
+            @text = hash_or_url[:text] || hash_or_url['text']
+            @title = hash_or_url[:title] || hash_or_url['title']
+            @link_type = hash_or_url[:link_type] || hash_or_url['link_type']
+          else
+            # Initialize from keyword arguments
+            @url = url || href || hash_or_url
+            @text = text
+            @title = title
+            @link_type = link_type
+          end
+        end
+        # rubocop:enable Metrics/CyclomaticComplexity
+
+        def to_h
+          {
+            url: @url,
+            text: @text,
+            title: @title,
+            link_type: @link_type
+          }.compact
+        end
+      end
+
+      # Represents a footnote in Djot content
+      class Footnote
+        attr_reader :label, :content
+
+        def initialize(label:, content:)
+          @label = label
+          @content = content
+        end
+
+        def to_h
+          {
+            label: @label,
+            content: @content
+          }
+        end
+      end
+
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      def initialize(hash)
+        @plain_text = hash['plain_text'] || hash[:plain_text] || ''
+        @blocks = parse_blocks(hash['blocks'] || hash[:blocks] || [])
+        @metadata_json = hash['metadata_json'] || hash[:metadata_json] || '{}'
+        @tables = hash['tables'] || hash[:tables] || []
+        @images = parse_images(hash['images'] || hash[:images] || [])
+        @links = parse_links(hash['links'] || hash[:links] || [])
+        @footnotes = parse_footnotes(hash['footnotes'] || hash[:footnotes] || [])
+        @attributes = hash['attributes'] || hash[:attributes] || {}
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+      def metadata
+        @metadata ||= parse_metadata(@metadata_json)
+      end
+
+      def to_h
+        {
+          plain_text: @plain_text,
+          blocks: @blocks.map(&:to_h),
+          metadata_json: @metadata_json,
+          tables: @tables,
+          images: @images.map(&:to_h),
+          links: @links.map(&:to_h),
+          footnotes: @footnotes.map(&:to_h),
+          attributes: @attributes
+        }
+      end
+
+      private
+
+      def parse_metadata(metadata_json)
+        JSON.parse(metadata_json)
+      rescue JSON::ParserError
+        {}
+      end
+
+      def parse_blocks(blocks_data)
+        blocks_data.map do |block|
+          FormattedBlock.new(
+            block_type: block['block_type'] || block[:block_type] || '',
+            children: block['children'] || block[:children],
+            attributes: block['attributes'] || block[:attributes]
+          )
+        end
+      end
+
+      # rubocop:disable Metrics/CyclomaticComplexity
+      def parse_images(images_data)
+        images_data.map do |image|
+          DjotImage.new(
+            url: image['url'] || image[:url] || image['src'] || image[:src],
+            alt: image['alt'] || image[:alt],
+            title: image['title'] || image[:title],
+            width: image['width'] || image[:width],
+            height: image['height'] || image[:height]
+          )
+        end
+      end
+      # rubocop:enable Metrics/CyclomaticComplexity
+
+      # rubocop:disable Metrics/CyclomaticComplexity
+      def parse_links(links_data)
+        links_data.map do |link|
+          DjotLink.new(
+            url: link['url'] || link[:url] || link['href'] || link[:href],
+            text: link['text'] || link[:text],
+            title: link['title'] || link[:title],
+            link_type: link['link_type'] || link[:link_type]
+          )
+        end
+      end
+      # rubocop:enable Metrics/CyclomaticComplexity
+
+      def parse_footnotes(footnotes_data)
+        footnotes_data.map do |note|
+          Footnote.new(
+            label: note['label'] || note[:label],
+            content: note['content'] || note[:content]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/kreuzberg/extraction_api.rb

@@ -15,11 +15,15 @@ module Kreuzberg
     # @example Extract with explicit MIME type
     # @example Extract with OCR enabled
     def extract_file_sync(path:, mime_type: nil, config: nil)
+      # Validate that the file exists
+      path_str = path.to_s
+      raise Errors::IOError, "File not found: #{path_str}" unless File.exist?(path_str)
+
       opts = normalize_config(config)
       hash = if mime_type
-               native_extract_file_sync(path.to_s, mime_type.to_s, **opts)
+               native_extract_file_sync(path_str, mime_type.to_s, **opts)
              else
-               native_extract_file_sync(path.to_s, **opts)
+               native_extract_file_sync(path_str, **opts)
              end
       result = Result.new(hash)
       record_cache_entry!(result, opts)
@@ -53,6 +57,8 @@ module Kreuzberg
     #   response = HTTParty.get("https://example.com/document.docx")
     #   result = Kreuzberg.extract_bytes_sync(response.body, "application/vnd.openxmlformats-officedocument.wordprocessingml.document")
     def extract_bytes_sync(data:, mime_type:, config: nil)
+      raise TypeError, "mime_type must be a String, got #{mime_type.inspect}" if mime_type.nil?
+
       opts = normalize_config(config)
       hash = native_extract_bytes_sync(data.to_s, mime_type.to_s, **opts)
       result = Result.new(hash)
@@ -92,6 +98,12 @@ module Kreuzberg
     #   config = Kreuzberg::Config::Extraction.new(force_ocr: true)
     #   results = Kreuzberg.batch_extract_files_sync(paths, config: config)
     def batch_extract_files_sync(paths:, config: nil)
+      # Validate that all files exist
+      paths.each do |path|
+        path_str = path.to_s
+        raise Errors::IOError, "File not found: #{path_str}" unless File.exist?(path_str)
+      end
+
       opts = normalize_config(config)
       hashes = native_batch_extract_files_sync(paths.map(&:to_s), **opts)
       results = hashes.map { |hash| Result.new(hash) }
@@ -130,11 +142,15 @@ module Kreuzberg
     #   )
     #   result = Kreuzberg.extract_file("document.pdf", config: config)
     def extract_file(path:, mime_type: nil, config: nil)
+      # Validate that the file exists
+      path_str = path.to_s
+      raise Errors::IOError, "File not found: #{path_str}" unless File.exist?(path_str)
+
       opts = normalize_config(config)
       hash = if mime_type
-               native_extract_file(path.to_s, mime_type.to_s, **opts)
+               native_extract_file(path_str, mime_type.to_s, **opts)
              else
-               native_extract_file(path.to_s, **opts)
+               native_extract_file(path_str, **opts)
              end
       result = Result.new(hash)
       record_cache_entry!(result, opts)