kreuzberg 4.0.0.rc2 → 4.0.0

data/sig/kreuzberg.rbs

@@ -1,520 +1,561 @@
-# Type signatures for Kreuzberg document intelligence framework
-
-module Kreuzberg
-  VERSION: String
-
-  # Error code constants
-  ERROR_CODE_SUCCESS: Integer
-  ERROR_CODE_GENERIC: Integer
-  ERROR_CODE_PANIC: Integer
-  ERROR_CODE_INVALID_ARGUMENT: Integer
-  ERROR_CODE_IO: Integer
-  ERROR_CODE_PARSING: Integer
-  ERROR_CODE_OCR: Integer
-  ERROR_CODE_MISSING_DEPENDENCY: Integer
-
-  # Config namespace (defined in lib/kreuzberg/config.rb)
-  module Config
-    class OCR
-      attr_reader backend: String
-      attr_reader language: String
-      attr_reader tesseract_config: Tesseract?
-
-      def initialize: (?backend: String, ?language: String, ?tesseract_config: (Tesseract | Hash[Symbol, untyped])?) -> void
-      def to_h: () -> Hash[Symbol, untyped]
-    end
-
-    class Tesseract
-      def initialize: (**untyped options) -> void
-      def to_h: () -> Hash[Symbol, untyped]
-    end
-
-    class Chunking
-      attr_reader max_chars: Integer
-      attr_reader max_overlap: Integer
-      attr_reader preset: String?
-      attr_reader embedding: Embedding?
-      attr_reader enabled: bool?
-
-      def initialize: (
-        ?max_chars: Integer?,
-        ?max_overlap: Integer?,
-        ?preset: String?,
-        ?embedding: (Embedding | Hash[Symbol, untyped])?,
-        ?chunk_size: Integer?,
-        ?chunk_overlap: Integer?,
-        ?enabled: bool
-      ) -> void
-      def to_h: () -> Hash[Symbol, untyped]
-    end
-
-    class Embedding
-      attr_reader model: Hash[Symbol, untyped]
-      attr_reader normalize: bool?
-      attr_reader batch_size: Integer?
-      attr_reader show_download_progress: bool?
-      attr_reader cache_dir: String?
-
-      def initialize: (
-        ?model: Hash[Symbol, untyped],
-        ?normalize: bool?,
-        ?batch_size: Integer?,
-        ?show_download_progress: bool?,
-        ?cache_dir: String?
-      ) -> void
-      def to_h: () -> Hash[Symbol, untyped]
-    end
-
-    class LanguageDetection
-      attr_reader enabled: bool
-      attr_reader min_confidence: Float
-      attr_reader detect_multiple: bool
-
-      def initialize: (?enabled: bool, ?min_confidence: Float, ?detect_multiple: bool) -> void
-      def to_h: () -> Hash[Symbol, untyped]
-    end
-
-    class PDF
-      attr_reader extract_images: bool
-      attr_reader passwords: Array[String]?
-      attr_reader extract_metadata: bool
-
-      def initialize: (?extract_images: bool, ?passwords: (Array[String] | String)?, ?extract_metadata: bool) -> void
-      def to_h: () -> Hash[Symbol, untyped]
-    end
-
-    class ImageExtraction
-      attr_reader extract_images: bool
-      attr_reader target_dpi: Integer
-      attr_reader max_image_dimension: Integer
-      attr_reader auto_adjust_dpi: bool
-      attr_reader min_dpi: Integer
-      attr_reader max_dpi: Integer
-
-      def initialize: (
-        ?extract_images: bool,
-        ?target_dpi: Integer,
-        ?max_image_dimension: Integer,
-        ?auto_adjust_dpi: bool,
-        ?min_dpi: Integer,
-        ?max_dpi: Integer
-      ) -> void
-      def to_h: () -> Hash[Symbol, untyped]
-    end
-
-    class ImagePreprocessing
-      attr_reader target_dpi: Integer
-      attr_reader auto_rotate: bool
-      attr_reader deskew: bool
-      attr_reader denoise: bool
-      attr_reader contrast_enhance: bool
-      attr_reader binarization_method: String
-      attr_reader invert_colors: bool
-
-      def initialize: (
-        ?target_dpi: Integer,
-        ?auto_rotate: bool,
-        ?deskew: bool,
-        ?denoise: bool,
-        ?contrast_enhance: bool,
-        ?binarization_method: String,
-        ?invert_colors: bool
-      ) -> void
-      def to_h: () -> Hash[Symbol, untyped]
-    end
-
-    class TokenReduction
-      attr_reader mode: String
-      attr_reader preserve_important_words: bool
-
-      def initialize: (?mode: String, ?preserve_important_words: bool) -> void
-      def to_h: () -> Hash[Symbol, untyped]
-    end
-
-    class PostProcessor
-      attr_reader enabled: bool
-      attr_reader enabled_processors: Array[String]?
-      attr_reader disabled_processors: Array[String]?
-
-      def initialize: (?enabled: bool, ?enabled_processors: Array[String]?, ?disabled_processors: Array[String]?) -> void
-      def to_h: () -> Hash[Symbol, untyped]
-    end
-
-    class HtmlPreprocessing
-      attr_reader enabled: bool?
-      attr_reader preset: Symbol?
-      attr_reader remove_navigation: bool?
-      attr_reader remove_forms: bool?
-
-      def initialize: (?enabled: bool?, ?preset: Symbol?, ?remove_navigation: bool?, ?remove_forms: bool?) -> void
-      def to_h: () -> Hash[Symbol, untyped]
-    end
-
-    class HtmlOptions
-      def initialize: (**untyped options) -> void
-      def to_h: () -> Hash[Symbol, untyped]
-    end
-
-    class Keywords
-      def initialize: (
-        ?algorithm: Symbol?,
-        ?max_keywords: Integer?,
-        ?min_score: Float?,
-        ?ngram_range: Array[Integer]?,
-        ?language: Symbol?,
-        ?yake_params: Hash[Symbol, untyped]?,
-        ?rake_params: Hash[Symbol, untyped]?
-      ) -> void
-      def to_h: () -> Hash[Symbol, untyped]
-    end
-
-    class Extraction
-      attr_reader use_cache: bool
-      attr_reader enable_quality_processing: bool
-      attr_reader force_ocr: bool
-      attr_reader ocr: OCR?
-      attr_reader chunking: Chunking?
-      attr_reader language_detection: LanguageDetection?
-      attr_reader pdf_options: PDF?
-      attr_reader image_extraction: ImageExtraction?
-      attr_reader image_preprocessing: ImagePreprocessing?
-      attr_reader postprocessor: PostProcessor?
-      attr_reader token_reduction: TokenReduction?
-      attr_reader keywords: Keywords?
-      attr_reader html_options: HtmlOptions?
-      attr_reader max_concurrent_extractions: Integer?
-
-      def self.from_file: (String path) -> Extraction
-      def initialize: (
-        ?use_cache: bool,
-        ?enable_quality_processing: bool,
-        ?force_ocr: bool,
-        ?ocr: (OCR | Hash[Symbol, untyped])?,
-        ?chunking: (Chunking | Hash[Symbol, untyped])?,
-        ?language_detection: (LanguageDetection | Hash[Symbol, untyped])?,
-        ?pdf_options: (PDF | Hash[Symbol, untyped])?,
-        ?image_extraction: (ImageExtraction | Hash[Symbol, untyped])?,
-        ?image_preprocessing: (ImagePreprocessing | Hash[Symbol, untyped])?,
-        ?postprocessor: (PostProcessor | Hash[Symbol, untyped])?,
-        ?token_reduction: (TokenReduction | Hash[Symbol, untyped])?,
-        ?keywords: (Keywords | Hash[Symbol, untyped])?,
-        ?html_options: (HtmlOptions | Hash[Symbol, untyped])?,
-        ?max_concurrent_extractions: Integer?
-      ) -> void
-      def to_h: () -> Hash[Symbol, untyped]
-
-      private
-
-      def normalize_config: [T] (T | Hash[Symbol, untyped] | nil value, Class klass) -> T?
-    end
-
-    # Backwards compatibility alias
-    Ocr: singleton(OCR)
-  end
-
-  # Alias for Config::Extraction (for API consistency with other language bindings)
-  ExtractionConfig: singleton(Config::Extraction)
-
-  # Extraction result type
-  type extraction_result_hash = {
-    content: String,
-    mime_type: String,
-    metadata_json: String,
-    tables: Array[table_hash]?,
-    detected_languages: Array[String]?,
-    chunks: Array[chunk_hash]?,
-    images: Array[image_hash]?
-  }
-
-  type table_hash = {
-    cells: Array[Array[String]],
-    markdown: String,
-    page_number: Integer
-  }
-
-  type chunk_hash = {
-    content: String,
-    char_start: Integer,
-    char_end: Integer,
-    token_count: Integer?,
-    chunk_index: Integer?,
-    total_chunks: Integer?,
-    embedding: Array[Float]?
-  }
-
-  type image_hash = {
-    data: String,
-    format: String,
-    image_index: Integer,
-    page_number: Integer?,
-    width: Integer?,
-    height: Integer?,
-    colorspace: String?,
-    bits_per_component: Integer?,
-    is_mask: bool?,
-    description: String?,
-    ocr_result: extraction_result_hash?
-  }
-
-  type config_hash = Hash[Symbol, untyped]
-  type config_input = config_hash | _ToH
-
-  interface _ToH
-    def to_h: () -> config_hash
-  end
-
-  # Extraction result wrapper
-  class Result
-    # Table structure
-    class Table
-      attr_reader cells: Array[Array[String]]
-      attr_reader markdown: String
-      attr_reader page_number: Integer
-
-      def initialize: (cells: Array[Array[String]], markdown: String, page_number: Integer) -> void
-      def to_h: () -> table_hash
-    end
-
-    # Text chunk
-    class Chunk
-      attr_reader content: String
-      attr_reader char_start: Integer
-      attr_reader char_end: Integer
-      attr_reader token_count: Integer?
-      attr_reader chunk_index: Integer?
-      attr_reader total_chunks: Integer?
-      attr_reader embedding: Array[Float]?
-
-      def initialize: (
-        content: String,
-        char_start: Integer,
-        char_end: Integer,
-        token_count: Integer?,
-        chunk_index: Integer?,
-        total_chunks: Integer?,
-        embedding: Array[Float]?
-      ) -> void
-      def to_h: () -> chunk_hash
-    end
-
-    class Image
-      attr_reader data: String
-      attr_reader format: String
-      attr_reader image_index: Integer
-      attr_reader page_number: Integer?
-      attr_reader width: Integer?
-      attr_reader height: Integer?
-      attr_reader colorspace: String?
-      attr_reader bits_per_component: Integer?
-      attr_reader is_mask: bool?
-      attr_reader description: String?
-      attr_reader ocr_result: Result?
-
-      def initialize: (
-        data: String,
-        format: String,
-        image_index: Integer,
-        page_number: Integer?,
-        width: Integer?,
-        height: Integer?,
-        colorspace: String?,
-        bits_per_component: Integer?,
-        is_mask: bool?,
-        description: String?,
-        ocr_result: Result?
-      ) -> void
-      def to_h: () -> image_hash
-    end
-
-    attr_reader content: String
-    attr_reader mime_type: String
-    attr_reader metadata: Hash[untyped, untyped]
-    attr_reader metadata_json: String
-    attr_reader tables: Array[Table]
-    attr_reader detected_languages: Array[String]?
-    attr_reader chunks: Array[Chunk]?
-    attr_reader images: Array[Image]?
-
-    def initialize: (extraction_result_hash hash) -> void
-    def to_h: () -> Hash[Symbol, untyped]
-    def to_json: (*untyped) -> String
-
-    private
-
-    def parse_metadata: (String metadata_json) -> Hash[untyped, untyped]
-    def parse_tables: (Array[table_hash]? tables_data) -> Array[Table]
-    def parse_detected_languages: (Array[String]? langs_data) -> Array[String]?
-    def parse_chunks: (Array[chunk_hash]? chunks_data) -> Array[Chunk]?
-  end
-
-  # Module methods (extraction API)
-  def self.extract_file_sync: (
-    String | Pathname path,
-    ?mime_type: String?,
-    ?config: config_input?
-  ) -> Result
-
-  def self.extract_bytes_sync: (
-    String data,
-    String mime_type,
-    ?config: config_input?
-  ) -> Result
-
-  def self.batch_extract_files_sync: (
-    Array[String | Pathname] paths,
-    ?config: config_input?
-  ) -> Array[Result]
-
-  def self.batch_extract_bytes_sync: (
-    Array[String] data_array,
-    Array[String] mime_types,
-    ?config: config_input?
-  ) -> Array[Result]
-
-  def self.extract_file: (
-    String | Pathname path,
-    ?mime_type: String?,
-    ?config: config_input?
-  ) -> Result
-
-  def self.extract_bytes: (
-    String data,
-    String mime_type,
-    ?config: config_input?
-  ) -> Result
-
-  def self.batch_extract_files: (
-    Array[String | Pathname] paths,
-    ?config: config_input?
-  ) -> Array[Result]
-
-  def self.batch_extract_bytes: (
-    Array[String] data_array,
-    Array[String] mime_types,
-    ?config: config_input?
-  ) -> Array[Result]
-
-  # Cache API
-  def self.clear_cache: () -> void
-  def self.cache_stats: () -> Hash[Symbol | String, Integer]
-
-  # Config loading (native method)
-  def self._config_from_file_native: (String path) -> Hash[Symbol, untyped]
-
-  # Error introspection (native methods)
-  def self._last_error_code_native: () -> Integer
-  def self._last_panic_context_json_native: () -> String?
-
-  # Plugin registration
-  def self.register_post_processor: (String name, _PostProcessor processor, ?stage: Symbol?) -> void
-  def self.unregister_post_processor: (String name) -> void
-  def self.clear_post_processors: () -> void
-  def self.register_validator: (String name, _Validator validator, ?priority: Integer?) -> void
-  def self.unregister_validator: (String name) -> void
-  def self.clear_validators: () -> void
-  def self.register_ocr_backend: (_OcrBackend backend) -> void
-
-  interface _PostProcessor
-    def call: (extraction_result_hash result) -> extraction_result_hash
-  end
-
-  interface _Validator
-    def call: (extraction_result_hash result) -> void
-  end
-
-  interface _OcrBackend
-    def name: () -> String
-    def extract_text: (String file_path_or_bytes, Hash[Symbol, untyped] config) -> String
-  end
-
-  module ErrorContext
-    def self.last_error_code: () -> Integer
-    def self.last_panic_context: () -> Errors::PanicContext?
-    def self.last_panic_context_json: () -> String?
-  end
-
-  module Errors
-    # Panic context information from FFI error introspection
-    class PanicContext
-      attr_reader file: String
-      attr_reader line: Integer
-      attr_reader function: String
-      attr_reader message: String
-      attr_reader timestamp_secs: Integer
-
-      def initialize: (
-        file: String,
-        line: Integer,
-        function: String,
-        message: String,
-        timestamp_secs: Integer
-      ) -> void
-      def to_s: () -> String
-      def to_h: () -> Hash[Symbol, String | Integer]
-      def self.from_json: (String) -> PanicContext?
-
-      private
-
-      def self.with_defaults: (Hash[Symbol, untyped] sliced) -> {file: String, line: Integer, function: String, message: String, timestamp_secs: Integer}
-    end
-
-    class Error < StandardError
-      attr_reader panic_context: PanicContext?
-      attr_reader error_code: Integer?
-
-      def initialize: (String message, ?panic_context: PanicContext?, ?error_code: Integer?) -> void
-    end
-
-    class ValidationError < Error
-    end
-
-    class ParsingError < Error
-      attr_reader context: Hash[untyped, untyped]?
-
-      def initialize: (String message, ?context: Hash[untyped, untyped]?, ?panic_context: PanicContext?, ?error_code: Integer?) -> void
-    end
-
-    class OCRError < Error
-      attr_reader context: Hash[untyped, untyped]?
-
-      def initialize: (String message, ?context: Hash[untyped, untyped]?, ?panic_context: PanicContext?, ?error_code: Integer?) -> void
-    end
-
-    class MissingDependencyError < Error
-      attr_reader dependency: String?
-
-      def initialize: (String message, ?dependency: String?, ?panic_context: PanicContext?, ?error_code: Integer?) -> void
-    end
-
-    class IOError < Error
-    end
-
-    class PluginError < Error
-    end
-
-    class UnsupportedFormatError < Error
-    end
-  end
-
-  # Internal modules (prepended to Kreuzberg singleton)
-  # These are not checked by steep - see Steepfile
-  module CacheAPI : Object
-  end
-
-  module ExtractionAPI : Object
-  end
-
-  module PostProcessorProtocol
-    def call: (extraction_result_hash result) -> extraction_result_hash
-  end
-
-  module ValidatorProtocol
-    def call: (extraction_result_hash result) -> void
-  end
-
-  module OcrBackendProtocol
-    def name: () -> String
-    def extract_text: (String file_path_or_bytes, Hash[Symbol, untyped] config) -> String
-    def process_image: (String file_path_or_bytes, Hash[Symbol, untyped] config) -> String
-  end
-end
+# Type signatures for Kreuzberg document intelligence framework
+
+module Kreuzberg
+  VERSION: String
+
+  # Error code constants
+  ERROR_CODE_SUCCESS: Integer
+  ERROR_CODE_GENERIC: Integer
+  ERROR_CODE_PANIC: Integer
+  ERROR_CODE_INVALID_ARGUMENT: Integer
+  ERROR_CODE_IO: Integer
+  ERROR_CODE_PARSING: Integer
+  ERROR_CODE_OCR: Integer
+  ERROR_CODE_MISSING_DEPENDENCY: Integer
+
+  # Config namespace (defined in lib/kreuzberg/config.rb)
+  module Config
+    class OCR
+      attr_reader backend: String
+      attr_reader language: String
+      attr_reader tesseract_config: Tesseract?
+
+      def initialize: (?backend: String, ?language: String, ?tesseract_config: (Tesseract | Hash[Symbol, untyped])?) -> void
+      def to_h: () -> Hash[Symbol, untyped]
+    end
+
+    class Tesseract
+      def initialize: (**untyped options) -> void
+      def to_h: () -> Hash[Symbol, untyped]
+    end
+
+    class Chunking
+      attr_reader max_chars: Integer
+      attr_reader max_overlap: Integer
+      attr_reader preset: String?
+      attr_reader embedding: Embedding?
+      attr_reader enabled: bool?
+
+      def initialize: (
+        ?max_chars: Integer?,
+        ?max_overlap: Integer?,
+        ?preset: String?,
+        ?embedding: (Embedding | Hash[Symbol, untyped])?,
+        ?chunk_size: Integer?,
+        ?chunk_overlap: Integer?,
+        ?enabled: bool
+      ) -> void
+      def to_h: () -> Hash[Symbol, untyped]
+    end
+
+    class Embedding
+      attr_reader model: Hash[Symbol, untyped]
+      attr_reader normalize: bool?
+      attr_reader batch_size: Integer?
+      attr_reader show_download_progress: bool?
+      attr_reader cache_dir: String?
+
+      def initialize: (
+        ?model: Hash[Symbol, untyped],
+        ?normalize: bool?,
+        ?batch_size: Integer?,
+        ?show_download_progress: bool?,
+        ?cache_dir: String?
+      ) -> void
+      def to_h: () -> Hash[Symbol, untyped]
+    end
+
+    class LanguageDetection
+      attr_reader enabled: bool
+      attr_reader min_confidence: Float
+      attr_reader detect_multiple: bool
+
+      def initialize: (?enabled: bool, ?min_confidence: Float, ?detect_multiple: bool) -> void
+      def to_h: () -> Hash[Symbol, untyped]
+    end
+
+    class FontConfig
+      attr_accessor enabled: bool
+      attr_accessor custom_font_dirs: Array[String]?
+
+      def initialize: (?enabled: bool, ?custom_font_dirs: Array[String]?) -> void
+      def to_h: () -> Hash[Symbol, untyped]
+    end
+
+    class PDF
+      attr_reader extract_images: bool
+      attr_reader passwords: Array[String]?
+      attr_reader extract_metadata: bool
+      attr_reader font_config: FontConfig?
+
+      def initialize: (?extract_images: bool, ?passwords: (Array[String] | String)?, ?extract_metadata: bool, ?font_config: (FontConfig | Hash[Symbol, untyped])?) -> void
+      def to_h: () -> Hash[Symbol, untyped]
+    end
+
+    class ImageExtraction
+      attr_reader extract_images: bool
+      attr_reader target_dpi: Integer
+      attr_reader max_image_dimension: Integer
+      attr_reader auto_adjust_dpi: bool
+      attr_reader min_dpi: Integer
+      attr_reader max_dpi: Integer
+
+      def initialize: (
+        ?extract_images: bool,
+        ?target_dpi: Integer,
+        ?max_image_dimension: Integer,
+        ?auto_adjust_dpi: bool,
+        ?min_dpi: Integer,
+        ?max_dpi: Integer
+      ) -> void
+      def to_h: () -> Hash[Symbol, untyped]
+    end
+
+    class ImagePreprocessing
+      attr_reader target_dpi: Integer
+      attr_reader auto_rotate: bool
+      attr_reader deskew: bool
+      attr_reader denoise: bool
+      attr_reader contrast_enhance: bool
+      attr_reader binarization_method: String
+      attr_reader invert_colors: bool
+
+      def initialize: (
+        ?target_dpi: Integer,
+        ?auto_rotate: bool,
+        ?deskew: bool,
+        ?denoise: bool,
+        ?contrast_enhance: bool,
+        ?binarization_method: String,
+        ?invert_colors: bool
+      ) -> void
+      def to_h: () -> Hash[Symbol, untyped]
+    end
+
+    class TokenReduction
+      attr_reader mode: String
+      attr_reader preserve_important_words: bool
+
+      def initialize: (?mode: String, ?preserve_important_words: bool) -> void
+      def to_h: () -> Hash[Symbol, untyped]
+    end
+
+    class PostProcessor
+      attr_reader enabled: bool
+      attr_reader enabled_processors: Array[String]?
+      attr_reader disabled_processors: Array[String]?
+
+      def initialize: (?enabled: bool, ?enabled_processors: Array[String]?, ?disabled_processors: Array[String]?) -> void
+      def to_h: () -> Hash[Symbol, untyped]
+    end
+
+    class HtmlPreprocessing
+      attr_reader enabled: bool?
+      attr_reader preset: Symbol?
+      attr_reader remove_navigation: bool?
+      attr_reader remove_forms: bool?
+
+      def initialize: (?enabled: bool?, ?preset: Symbol?, ?remove_navigation: bool?, ?remove_forms: bool?) -> void
+      def to_h: () -> Hash[Symbol, untyped]
+    end
+
+    class HtmlOptions
+      def initialize: (**untyped options) -> void
+      def to_h: () -> Hash[Symbol, untyped]
+    end
+
+    class Keywords
+      def initialize: (
+        ?algorithm: Symbol?,
+        ?max_keywords: Integer?,
+        ?min_score: Float?,
+        ?ngram_range: Array[Integer]?,
+        ?language: Symbol?,
+        ?yake_params: Hash[Symbol, untyped]?,
+        ?rake_params: Hash[Symbol, untyped]?
+      ) -> void
+      def to_h: () -> Hash[Symbol, untyped]
+    end
+
+    class PageConfig
+      attr_reader extract_pages: bool
+      attr_reader insert_page_markers: bool
+      attr_reader marker_format: String
+
+      def initialize: (?extract_pages: bool, ?insert_page_markers: bool, ?marker_format: String) -> void
+      def to_h: () -> Hash[Symbol, untyped]
+    end
+
+    class Extraction
+      attr_reader use_cache: bool
+      attr_reader enable_quality_processing: bool
+      attr_reader force_ocr: bool
+      attr_reader ocr: OCR?
+      attr_reader chunking: Chunking?
+      attr_reader language_detection: LanguageDetection?
+      attr_reader pdf_options: PDF?
+      attr_reader image_extraction: ImageExtraction?
+      attr_reader image_preprocessing: ImagePreprocessing?
+      attr_reader postprocessor: PostProcessor?
+      attr_reader token_reduction: TokenReduction?
+      attr_reader keywords: Keywords?
+      attr_reader html_options: HtmlOptions?
+      attr_reader pages: PageConfig?
+      attr_reader max_concurrent_extractions: Integer?
+
+      def self.from_file: (String path) -> Extraction
+      def initialize: (
+        ?use_cache: bool,
+        ?enable_quality_processing: bool,
+        ?force_ocr: bool,
+        ?ocr: (OCR | Hash[Symbol, untyped])?,
+        ?chunking: (Chunking | Hash[Symbol, untyped])?,
+        ?language_detection: (LanguageDetection | Hash[Symbol, untyped])?,
+        ?pdf_options: (PDF | Hash[Symbol, untyped])?,
+        ?image_extraction: (ImageExtraction | Hash[Symbol, untyped])?,
+        ?image_preprocessing: (ImagePreprocessing | Hash[Symbol, untyped])?,
+        ?postprocessor: (PostProcessor | Hash[Symbol, untyped])?,
+        ?token_reduction: (TokenReduction | Hash[Symbol, untyped])?,
+        ?keywords: (Keywords | Hash[Symbol, untyped])?,
+        ?html_options: (HtmlOptions | Hash[Symbol, untyped])?,
+        ?pages: (PageConfig | Hash[Symbol, untyped])?,
+        ?max_concurrent_extractions: Integer?
+      ) -> void
+      def to_h: () -> Hash[Symbol, untyped]
+
+      private
+
+      def normalize_config: [T] (T | Hash[Symbol, untyped] | nil value, Class klass) -> T?
+    end
+
+  end
+
+  # Alias for Config::Extraction (for API consistency with other language bindings)
+  ExtractionConfig: singleton(Config::Extraction)
+
+  # Alias for Config::PageConfig (for API consistency with other language bindings)
+  PageConfig: singleton(Config::PageConfig)
+
+  # Keyword algorithm constants
+  module KeywordAlgorithm
+    YAKE: Symbol
+    RAKE: Symbol
+  end
+
+  # Extraction result type
+  type extraction_result_hash = {
+    content: String,
+    mime_type: String,
+    metadata_json: String,
+    tables: Array[table_hash]?,
+    detected_languages: Array[String]?,
+    chunks: Array[chunk_hash]?,
+    images: Array[image_hash]?
+  }
+
+  type table_hash = {
+    cells: Array[Array[String]],
+    markdown: String,
+    page_number: Integer
+  }
+
+  type chunk_hash = {
+    content: String,
+    byte_start: Integer,
+    byte_end: Integer,
+    token_count: Integer?,
+    chunk_index: Integer?,
+    total_chunks: Integer?,
+    first_page: Integer?,
+    last_page: Integer?,
+    embedding: Array[Float]?
+  }
+
+  type image_hash = {
+    data: String,
+    format: String,
+    image_index: Integer,
+    page_number: Integer?,
+    width: Integer?,
+    height: Integer?,
+    colorspace: String?,
+    bits_per_component: Integer?,
+    is_mask: bool?,
+    description: String?,
+    ocr_result: extraction_result_hash?
+  }
+
+  type config_hash = Hash[Symbol, untyped]
+  type config_input = config_hash | _ToH
+
+  interface _ToH
+    def to_h: () -> config_hash
+  end
+
+  # Extraction result wrapper
+  class Result
+    # Table structure
+    class Table
+      attr_reader cells: Array[Array[String]]
+      attr_reader markdown: String
+      attr_reader page_number: Integer
+
+      def initialize: (cells: Array[Array[String]], markdown: String, page_number: Integer) -> void
+      def to_h: () -> table_hash
+    end
+
+    # Text chunk
+    class Chunk
+      attr_reader content: String
+      attr_reader byte_start: Integer
+      attr_reader byte_end: Integer
+      attr_reader token_count: Integer?
+      attr_reader chunk_index: Integer?
+      attr_reader total_chunks: Integer?
+      attr_reader first_page: Integer?
+      attr_reader last_page: Integer?
+      attr_reader embedding: Array[Float]?
+
+      def initialize: (
+        content: String,
+        byte_start: Integer,
+        byte_end: Integer,
+        token_count: Integer?,
+        chunk_index: Integer?,
+        total_chunks: Integer?,
+        first_page: Integer?,
+        last_page: Integer?,
+        embedding: Array[Float]?
+      ) -> void
+      def to_h: () -> chunk_hash
+    end
+
+    class Image
+      attr_reader data: String
+      attr_reader format: String
+      attr_reader image_index: Integer
+      attr_reader page_number: Integer?
+      attr_reader width: Integer?
+      attr_reader height: Integer?
+      attr_reader colorspace: String?
+      attr_reader bits_per_component: Integer?
+      attr_reader is_mask: bool?
+      attr_reader description: String?
+      attr_reader ocr_result: Result?
+
+      def initialize: (
+        data: String,
+        format: String,
+        image_index: Integer,
+        page_number: Integer?,
+        width: Integer?,
+        height: Integer?,
+        colorspace: String?,
+        bits_per_component: Integer?,
+        is_mask: bool?,
+        description: String?,
+        ocr_result: Result?
+      ) -> void
+      def to_h: () -> image_hash
+    end
+
+    attr_reader content: String
+    attr_reader mime_type: String
+    attr_reader metadata: Hash[untyped, untyped]
+    attr_reader metadata_json: String
+    attr_reader tables: Array[Table]
+    attr_reader detected_languages: Array[String]?
+    attr_reader chunks: Array[Chunk]?
+    attr_reader images: Array[Image]?
+
+    def initialize: (extraction_result_hash hash) -> void
+    def to_h: () -> Hash[Symbol, untyped]
+    def to_json: (*untyped) -> String
+
+    private
+
+    def parse_metadata: (String metadata_json) -> Hash[untyped, untyped]
+    def parse_tables: (Array[table_hash]? tables_data) -> Array[Table]
+    def parse_detected_languages: (Array[String]? langs_data) -> Array[String]?
+    def parse_chunks: (Array[chunk_hash]? chunks_data) -> Array[Chunk]?
+  end
+
+  # Module methods (extraction API)
+  def self.extract_file_sync: (
+    String | Pathname path,
+    ?mime_type: String?,
+    ?config: config_input?
+  ) -> Result
+
+  def self.extract_bytes_sync: (
+    String data,
+    String mime_type,
+    ?config: config_input?
+  ) -> Result
+
+  def self.batch_extract_files_sync: (
+    Array[String | Pathname] paths,
+    ?config: config_input?
+  ) -> Array[Result]
+
+  def self.batch_extract_bytes_sync: (
+    Array[String] data_array,
+    Array[String] mime_types,
+    ?config: config_input?
+  ) -> Array[Result]
+
+  def self.extract_file: (
+    String | Pathname path,
+    ?mime_type: String?,
+    ?config: config_input?
+  ) -> Result
+
+  def self.extract_bytes: (
+    String data,
+    String mime_type,
+    ?config: config_input?
+  ) -> Result
+
+  def self.batch_extract_files: (
+    Array[String | Pathname] paths,
+    ?config: config_input?
+  ) -> Array[Result]
+
+  def self.batch_extract_bytes: (
+    Array[String] data_array,
+    Array[String] mime_types,
+    ?config: config_input?
+  ) -> Array[Result]
+
+  # Cache API
+  def self.clear_cache: () -> void
+  def self.cache_stats: () -> Hash[Symbol | String, Integer]
+
+  # Config loading (native method)
+  def self._config_from_file_native: (String path) -> Hash[Symbol, untyped]
+
+  # Error introspection (native methods)
+  def self._last_error_code_native: () -> Integer
+  def self._last_panic_context_json_native: () -> String?
+  def self._get_error_details_native: () -> Hash[Symbol, untyped]
+  def self._classify_error_native: (String message) -> Integer
+  def self._error_code_name_native: (Integer code) -> String
+  def self._error_code_description_native: (Integer code) -> String
+
+  # Plugin registration
+  def self.register_post_processor: (String name, _PostProcessor processor, ?stage: Symbol?) -> void
+  def self.unregister_post_processor: (String name) -> void
+  def self.clear_post_processors: () -> void
+  def self.register_validator: (String name, _Validator validator, ?priority: Integer?) -> void
+  def self.unregister_validator: (String name) -> void
+  def self.clear_validators: () -> void
+  def self.register_ocr_backend: (_OcrBackend backend) -> void
+
+  interface _PostProcessor
+    def call: (extraction_result_hash result) -> extraction_result_hash
+  end
+
+  interface _Validator
+    def call: (extraction_result_hash result) -> void
+  end
+
+  interface _OcrBackend
+    def name: () -> String
+    def extract_text: (String file_path_or_bytes, Hash[Symbol, untyped] config) -> String
+  end
+
+  module ErrorContext
+    def self.last_error_code: () -> Integer
+    def self.last_panic_context: () -> Errors::PanicContext?
+    def self.last_panic_context_json: () -> String?
+    def self.error_details: () -> Hash[Symbol, untyped]
+    def self.classify_error: (String message) -> Integer
+    def self.error_code_name: (Integer code) -> String
+    def self.error_code_description: (Integer code) -> String
+  end
+
+  module Errors
+    # Panic context information from FFI error introspection
+    class PanicContext
+      attr_reader file: String
+      attr_reader line: Integer
+      attr_reader function: String
+      attr_reader message: String
+      attr_reader timestamp_secs: Integer
+
+      def initialize: (
+        file: String,
+        line: Integer,
+        function: String,
+        message: String,
+        timestamp_secs: Integer
+      ) -> void
+      def to_s: () -> String
+      def to_h: () -> Hash[Symbol, String | Integer]
+      def self.from_json: (String) -> PanicContext?
+
+      private
+
+      def self.with_defaults: (Hash[Symbol, untyped] sliced) -> {file: String, line: Integer, function: String, message: String, timestamp_secs: Integer}
+    end
+
+    class Error < StandardError
+      attr_reader panic_context: PanicContext?
+      attr_reader error_code: Integer?
+
+      def initialize: (String message, ?panic_context: PanicContext?, ?error_code: Integer?) -> void
+    end
+
+    class ValidationError < Error
+    end
+
+    class ParsingError < Error
+      attr_reader context: Hash[untyped, untyped]?
+
+      def initialize: (String message, ?context: Hash[untyped, untyped]?, ?panic_context: PanicContext?, ?error_code: Integer?) -> void
+    end
+
+    class OCRError < Error
+      attr_reader context: Hash[untyped, untyped]?
+
+      def initialize: (String message, ?context: Hash[untyped, untyped]?, ?panic_context: PanicContext?, ?error_code: Integer?) -> void
+    end
+
+    class MissingDependencyError < Error
+      attr_reader dependency: String?
+
+      def initialize: (String message, ?dependency: String?, ?panic_context: PanicContext?, ?error_code: Integer?) -> void
+    end
+
+    class IOError < Error
+    end
+
+    class PluginError < Error
+    end
+
+    class UnsupportedFormatError < Error
+    end
+  end
+
+  # Internal modules (prepended to Kreuzberg singleton)
+  # These are not checked by steep - see Steepfile
+  module CacheAPI : Object
+  end
+
+  module ExtractionAPI : Object
+  end
+
+  module PostProcessorProtocol
+    def call: (extraction_result_hash result) -> extraction_result_hash
+  end
+
+  module ValidatorProtocol
+    def call: (extraction_result_hash result) -> void
+  end
+
+  module OcrBackendProtocol
+    def name: () -> String
+    def extract_text: (String file_path_or_bytes, Hash[Symbol, untyped] config) -> String
+    def process_image: (String file_path_or_bytes, Hash[Symbol, untyped] config) -> String
+  end
+end