kreuzberg 4.10.0.pre.rc.15-aarch64-linux → 4.10.1-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bfe29f22cffdc678915c61571564fe1028c0eca5c47ff4e252ccfde8fd78a9e8
-  data.tar.gz: 70aaa78638d5cb73645d5f33e397b48bc5d386157e19b63bccc25c17f703e63a
+  metadata.gz: 92a5b6719c47d9736b83893d7af37e863cf0c0da027122b9a0b77950d2a32c1e
+  data.tar.gz: dbe3b460cce6759ebfd0628f4cfb5336c4244b5950b57578a2ca64e53d95b0ef
 SHA512:
-  metadata.gz: 0efd1ff7b70407c6267cae47ecad218a3d2efd3b25c9939d86d77a869ab242da38b468bdd130605546c6a6daaa0a99e4620e258ffc0b19950032d3675edf4f9a
-  data.tar.gz: 4bff3ab6839f6be482fbc27f57150fbc76a0eaa58c0e3ea7671525b3d62a0d0ea7334fb4c4619b60b1487bbfdda7410835a324157699142e41749272f3245715
+  metadata.gz: 3865d365deae1c064fcbc01ba32b3f17a14f3076d6703a73843cab317f3e29400309e92fe6bd915e291b54e99574406913b9d2ef5d976ad76fccb39808e7b597
+  data.tar.gz: 102c0d8ef33f64234e840c7459035baa5bdc3bfe8067160752139e6a3ece182d8c2720f316fde8c05ffea45e86b187601a5660e2db957b416ee5ae216d59ce3b

data/README.md

@@ -0,0 +1,435 @@
+# Ruby
+
+<div align="center" style="display: flex; flex-wrap: wrap; gap: 8px; justify-content: center; margin: 20px 0;">
+  <!-- Language Bindings -->
+  <a href="https://crates.io/crates/kreuzberg">
+    <img src="https://img.shields.io/crates/v/kreuzberg?label=Rust&color=007ec6" alt="Rust">
+  </a>
+  <a href="https://hex.pm/packages/kreuzberg">
+    <img src="https://img.shields.io/hexpm/v/kreuzberg?label=Elixir&color=007ec6" alt="Elixir">
+  </a>
+  <a href="https://pypi.org/project/kreuzberg/">
+    <img src="https://img.shields.io/pypi/v/kreuzberg?label=Python&color=007ec6" alt="Python">
+  </a>
+  <a href="https://www.npmjs.com/package/@kreuzberg/node">
+    <img src="https://img.shields.io/npm/v/@kreuzberg/node?label=Node.js&color=007ec6" alt="Node.js">
+  </a>
+  <a href="https://www.npmjs.com/package/@kreuzberg/wasm">
+    <img src="https://img.shields.io/npm/v/@kreuzberg/wasm?label=WASM&color=007ec6" alt="WASM">
+  </a>
+
+  <a href="https://central.sonatype.com/artifact/dev.kreuzberg/kreuzberg">
+    <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-lts/releases">
+    <img src="https://img.shields.io/github/v/tag/kreuzberg-dev/kreuzberg-lts?label=Go&color=007ec6&filter=v4.*" 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#">
+  </a>
+  <a href="https://packagist.org/packages/kreuzberg/kreuzberg">
+    <img src="https://img.shields.io/packagist/v/kreuzberg/kreuzberg?label=PHP&color=007ec6" alt="PHP">
+  </a>
+  <a href="https://rubygems.org/gems/kreuzberg">
+    <img src="https://img.shields.io/gem/v/kreuzberg?label=Ruby&color=007ec6" alt="Ruby">
+  </a>
+  <a href="https://kreuzberg-dev.r-universe.dev/kreuzberg">
+    <img src="https://img.shields.io/badge/R-kreuzberg-007ec6" alt="R">
+  </a>
+  <a href="https://github.com/kreuzberg-dev/kreuzberg-lts/pkgs/container/kreuzberg">
+    <img src="https://img.shields.io/badge/Docker-007ec6?logo=docker&logoColor=white" alt="Docker">
+  </a>
+  <a href="https://artifacthub.io/packages/search?repo=kreuzberg">
+    <img src="https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/kreuzberg" alt="Artifact Hub">
+  </a>
+
+  <!-- Project Info -->
+  <a href="https://github.com/kreuzberg-dev/kreuzberg-lts/blob/main/LICENSE">
+    <img src="https://img.shields.io/badge/License-MIT-007ec6" alt="License">
+  </a>
+  <a href="https://docs.kreuzberg.dev">
+    <img src="https://img.shields.io/badge/docs-kreuzberg.dev-007ec6" alt="Documentation">
+  </a>
+  <a href="https://docs.kreuzberg.dev/demo.html">
+    <img src="https://img.shields.io/badge/%E2%96%B6%EF%B8%8F_Live_Demo-007ec6" alt="Live Demo">
+  </a>
+  <a href="https://huggingface.co/Kreuzberg">
+    <img src="https://img.shields.io/badge/%F0%9F%A4%97_Hugging_Face-007ec6" alt="Hugging Face">
+  </a>
+</div>
+
+> [!NOTE]
+> **Kreuzberg v4 LTS** — the long-term-support line for Kreuzberg **v4**. Active development has moved to
+> **[Xberg](https://github.com/xberg-io/xberg)** (v5+), which receives all new features. This line receives
+> critical bug and security fixes until the **end of 2026, on a best-effort basis**.
+> See the **[migration guide & LTS policy →](https://docs.kreuzberg.dev/lts/)**
+
+<div align="center" style="margin-top: 20px;">
+  <a href="https://discord.gg/xt9WY3GnKR">
+      <img height="22" src="https://img.shields.io/badge/Discord-Join%20our%20community-7289da?logo=discord&logoColor=white" alt="Discord">
+  </a>
+</div>
+
+
+Extract text, tables, images, and metadata from 91+ file formats and 248 programming languages including PDF, Office documents, and images. Ruby bindings with idiomatic Ruby API and native performance.
+
+
+## Installation
+
+### Package Installation
+
+
+Install via one of the supported package managers:
+
+
+
+**gem:**
+
+```bash
+gem install kreuzberg
+```
+
+
+
+
+**Bundler:**
+
+```ruby
+gem 'kreuzberg'
+```
+
+
+
+
+
+### System Requirements
+
+- **Ruby 3.2.0 or higher** required (including Ruby 4.x)
+- Ruby 4.0+ is fully supported with no code changes required
+- Optional: [ONNX Runtime](https://github.com/microsoft/onnxruntime/releases) version 1.22.x for embeddings support
+- Optional: [Tesseract OCR](https://github.com/tesseract-ocr/tesseract) for OCR functionality
+
+**Ruby 4.0 Compatibility:** Kreuzberg is fully compatible with Ruby 4.0 (released December 25, 2025) and all Ruby 4.x versions. All tests pass with 100% compatibility. The gem compiles without any breaking changes. Key Ruby 4.0 features like Ruby Box, ZJIT compiler, and Ractor improvements work seamlessly with Kreuzberg.
+
+
+
+## Quick Start
+
+### Basic Extraction
+
+Extract text, metadata, and structure from any supported document format:
+
+```ruby
+require 'kreuzberg'
+
+result = Kreuzberg.extract_file_sync('document.pdf')
+
+puts "Content:"
+puts result.content
+
+puts "\nMetadata:"
+puts "Title: #{result.metadata&.dig('title')}"
+puts "Author: #{result.metadata&.dig('author')}"
+
+puts "\nTables found: #{result.tables.length}"
+puts "Images found: #{result.images.length}"
+```
+
+
+### Common Use Cases
+
+#### Extract with Custom Configuration
+
+Most use cases benefit from configuration to control extraction behavior:
+
+
+**With OCR (for scanned documents):**
+
+```ruby
+require 'kreuzberg'
+
+ocr_config = Kreuzberg::Config::OCR.new(
+  backend: 'tesseract',
+  language: 'eng'
+)
+
+config = Kreuzberg::Config::Extraction.new(ocr: ocr_config)
+result = Kreuzberg.extract_file_sync('scanned.pdf', config: config)
+
+puts "Extracted text from scanned document:"
+puts result.content
+puts "Used OCR backend: tesseract"
+```
+
+
+
+
+#### Table Extraction
+
+
+See [Table Extraction Guide](https://docs.kreuzberg.dev/features/table-extraction/) for detailed examples.
+
+
+
+#### Processing Multiple Files
+
+
+```ruby
+require 'kreuzberg'
+
+puts "Kreuzberg version: #{Kreuzberg::VERSION}"
+puts "FFI bindings loaded successfully"
+
+result = Kreuzberg.extract_file_sync('sample.pdf')
+puts "Installation verified! Extracted #{result.content.length} characters"
+```
+
+
+
+
+
+#### Async Processing
+
+For non-blocking document processing:
+
+```ruby
+require 'kreuzberg'
+
+config = Kreuzberg::Config::Extraction.new(
+  use_cache: true,
+  enable_quality_processing: true
+)
+
+result = Kreuzberg.extract_file_sync('contract.pdf', config: config)
+
+puts "Extracted #{result.content.length} characters"
+puts "Quality score: #{result.quality_score}"
+puts "Processing time: #{result.metadata&.dig('processing_time')}ms"
+```
+
+
+
+
+
+
+### Next Steps
+
+- **[Installation Guide](https://docs.kreuzberg.dev/getting-started/installation/)** - Platform-specific setup
+- **[API Documentation](https://docs.kreuzberg.dev/api/)** - Complete API reference
+- **[Examples & Guides](https://docs.kreuzberg.dev/guides/)** - Full code examples and usage guides
+- **[Configuration Guide](https://docs.kreuzberg.dev/guides/configuration/)** - Advanced configuration options
+
+
+
+## Features
+
+### Supported File Formats (91+)
+
+91+ file formats across 8 major categories with intelligent format detection and comprehensive metadata extraction.
+
+#### Office Documents
+
+| Category | Formats | Capabilities |
+|----------|---------|--------------|
+| **Word Processing** | `.docx`, `.docm`, `.dotx`, `.dotm`, `.dot`, `.odt` | Full text, tables, images, metadata, styles |
+| **Spreadsheets** | `.xlsx`, `.xlsm`, `.xlsb`, `.xls`, `.xla`, `.xlam`, `.xltm`, `.xltx`, `.xlt`, `.ods` | Sheet data, formulas, cell metadata, charts |
+| **Presentations** | `.pptx`, `.pptm`, `.ppsx`, `.potx`, `.potm`, `.pot`, `.ppt` | Slides, speaker notes, images, metadata |
+| **PDF** | `.pdf` | Text, tables, images, metadata, OCR support |
+| **eBooks** | `.epub`, `.fb2` | Chapters, metadata, embedded resources |
+| **Database** | `.dbf` | Table data extraction, field type support |
+| **Hangul** | `.hwp`, `.hwpx` | Korean document format, text extraction |
+
+#### Images (OCR-Enabled)
+
+| Category | Formats | Features |
+|----------|---------|----------|
+| **Raster** | `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.bmp`, `.tiff`, `.tif` | OCR, table detection, EXIF metadata, dimensions, color space |
+| **Advanced** | `.jp2`, `.jpx`, `.jpm`, `.mj2`, `.jbig2`, `.jb2`, `.pnm`, `.pbm`, `.pgm`, `.ppm` | OCR via hayro-jpeg2000 (pure Rust decoder), JBIG2 support, table detection, format-specific metadata |
+| **Vector** | `.svg` | DOM parsing, embedded text, graphics metadata |
+
+#### Web & Data
+
+| Category | Formats | Features |
+|----------|---------|----------|
+| **Markup** | `.html`, `.htm`, `.xhtml`, `.xml`, `.svg` | DOM parsing, metadata (Open Graph, Twitter Card), link extraction |
+| **Structured Data** | `.json`, `.yaml`, `.yml`, `.toml`, `.csv`, `.tsv` | Schema detection, nested structures, validation |
+| **Text & Markdown** | `.txt`, `.md`, `.markdown`, `.djot`, `.rst`, `.org`, `.rtf` | CommonMark, GFM, Djot, reStructuredText, Org Mode |
+
+#### Email & Archives
+
+| Category | Formats | Features |
+|----------|---------|----------|
+| **Email** | `.eml`, `.msg` | Headers, body (HTML/plain), attachments, threading |
+| **Archives** | `.zip`, `.tar`, `.tgz`, `.gz`, `.7z` | File listing, nested archives, metadata |
+
+#### Academic & Scientific
+
+| Category | Formats | Features |
+|----------|---------|----------|
+| **Citations** | `.bib`, `.biblatex`, `.ris`, `.nbib`, `.enw`, `.csl` | Structured parsing: RIS (structured), PubMed/MEDLINE, EndNote XML (structured), BibTeX, CSL JSON |
+| **Scientific** | `.tex`, `.latex`, `.typst`, `.jats`, `.ipynb`, `.docbook` | LaTeX, Jupyter notebooks, PubMed JATS |
+| **Documentation** | `.opml`, `.pod`, `.mdoc`, `.troff` | Technical documentation formats |
+
+#### Code Intelligence (248 Languages)
+
+| Feature | Description |
+|---------|-------------|
+| **Structure Extraction** | Functions, classes, methods, structs, interfaces, enums |
+| **Import/Export Analysis** | Module dependencies, re-exports, wildcard imports |
+| **Symbol Extraction** | Variables, constants, type aliases, properties |
+| **Docstring Parsing** | Google, NumPy, Sphinx, JSDoc, RustDoc, and 10+ formats |
+| **Diagnostics** | Parse errors with line/column positions |
+| **Syntax-Aware Chunking** | Split code by semantic boundaries, not arbitrary byte offsets |
+
+Powered by [tree-sitter-language-pack](https://github.com/xberg-io/tree-sitter-language-pack) — [documentation](https://docs.tree-sitter-language-pack.xberg.io).
+
+**[Complete Format Reference](https://docs.kreuzberg.dev/reference/formats/)**
+
+### Key Capabilities
+
+- **Text Extraction** - Extract all text content with position and formatting information
+- **Metadata Extraction** - Retrieve document properties, creation date, author, etc.
+- **Table Extraction** - Parse tables with structure and cell content preservation
+- **Image Extraction** - Extract embedded images and render page previews
+- **OCR Support** - Integrate multiple OCR backends for scanned documents
+
+- **Async/Await** - Non-blocking document processing with concurrent operations
+
+
+- **Plugin System** - Extensible post-processing for custom text transformation
+
+
+- **Embeddings** - Generate vector embeddings using ONNX Runtime models
+
+- **Batch Processing** - Efficiently process multiple documents in parallel
+- **Memory Efficient** - Stream large files without loading entirely into memory
+- **Language Detection** - Detect and support multiple languages in documents
+
+- **Code Intelligence** - Extract structure, imports, exports, symbols, and docstrings from [248 programming languages](https://docs.tree-sitter-language-pack.xberg.io) via tree-sitter
+
+- **Configuration** - Fine-grained control over extraction behavior
+
+### Performance Characteristics
+
+| Format | Speed | Memory | Notes |
+|--------|-------|--------|-------|
+| **PDF (text)** | 10-100 MB/s | ~50MB per doc | Fastest extraction |
+| **Office docs** | 20-200 MB/s | ~100MB per doc | DOCX, XLSX, PPTX |
+| **Images (OCR)** | 1-5 MB/s | Variable | Depends on OCR backend |
+| **Archives** | 5-50 MB/s | ~200MB per doc | ZIP, TAR, etc. |
+| **Web formats** | 50-200 MB/s | Streaming | HTML, XML, JSON |
+
+
+
+## OCR Support
+
+Kreuzberg supports multiple OCR backends for extracting text from scanned documents and images:
+
+
+- **Tesseract**
+
+- **Paddleocr**
+
+
+### OCR Configuration Example
+
+```ruby
+require 'kreuzberg'
+
+ocr_config = Kreuzberg::Config::OCR.new(
+  backend: 'tesseract',
+  language: 'eng'
+)
+
+config = Kreuzberg::Config::Extraction.new(ocr: ocr_config)
+result = Kreuzberg.extract_file_sync('scanned.pdf', config: config)
+
+puts "Extracted text from scanned document:"
+puts result.content
+puts "Used OCR backend: tesseract"
+```
+
+
+
+
+## Async Support
+
+This binding provides full async/await support for non-blocking document processing:
+
+```ruby
+require 'kreuzberg'
+
+config = Kreuzberg::Config::Extraction.new(
+  use_cache: true,
+  enable_quality_processing: true
+)
+
+result = Kreuzberg.extract_file_sync('contract.pdf', config: config)
+
+puts "Extracted #{result.content.length} characters"
+puts "Quality score: #{result.quality_score}"
+puts "Processing time: #{result.metadata&.dig('processing_time')}ms"
+```
+
+
+
+
+## Plugin System
+
+Kreuzberg supports extensible post-processing plugins for custom text transformation and filtering.
+
+For detailed plugin documentation, visit [Plugin System Guide](https://docs.kreuzberg.dev/guides/plugins/).
+
+
+
+
+## Embeddings Support
+
+Generate vector embeddings for extracted text using the built-in ONNX Runtime support. Requires ONNX Runtime installation.
+
+**[Embeddings Guide](https://docs.kreuzberg.dev/features/#embeddings)**
+
+
+
+## Batch Processing
+
+Process multiple documents efficiently:
+
+```ruby
+require 'kreuzberg'
+
+puts "Kreuzberg version: #{Kreuzberg::VERSION}"
+puts "FFI bindings loaded successfully"
+
+result = Kreuzberg.extract_file_sync('sample.pdf')
+puts "Installation verified! Extracted #{result.content.length} characters"
+```
+
+
+
+
+## Configuration
+
+For advanced configuration options including language detection, table extraction, OCR settings, and more:
+
+**[Configuration Guide](https://docs.kreuzberg.dev/guides/configuration/)**
+
+## Documentation
+
+- **[Official Documentation](https://docs.kreuzberg.dev/)**
+- **[API Reference](https://docs.kreuzberg.dev/reference/api-ruby/)**
+- **[Examples & Guides](https://docs.kreuzberg.dev/guides/)**
+
+## Contributing
+
+Contributions are welcome! See [Contributing Guide](https://github.com/kreuzberg-dev/kreuzberg-lts/blob/main/CONTRIBUTING.md).
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Support
+
+- **Discord Community**: [Join our Discord](https://discord.gg/xt9WY3GnKR)
+- **GitHub Issues**: [Report bugs](https://github.com/kreuzberg-dev/kreuzberg-lts/issues)
+- **Discussions**: [Ask questions](https://github.com/kreuzberg-dev/kreuzberg-lts/discussions)

data/lib/kreuzberg/api_proxy.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Kreuzberg
+  # @example Start the server
+  # @example With block
+  module APIProxy
+    class Error < Kreuzberg::Errors::Error
+    end
+
+    class MissingBinaryError < Error
+    end
+
+    class ServerError < Error
+    end
+
+    # API server instance
+    class Server
+      attr_reader :port, :host, :pid
+
+      # Initialize server
+      #
+      # @param port [Integer] Port to run on (default: 8000)
+      # @param host [String] Host to bind to (default: "0.0.0.0")
+      #
+      def initialize(port: 8000, host: "0.0.0.0")
+        @port = port
+        @host = host
+        @pid = nil
+        @process = nil
+      end
+
+      # Start the server in the background
+      #
+      # @return [Integer] Process ID
+      # @raise [ServerError] If server fails to start
+      #
+      def start
+        binary = APIProxy.find_api_binary
+        @pid = spawn(
+          binary.to_s,
+          "api",
+          "--host",
+          @host,
+          "--port",
+          @port.to_s,
+          out: $stdout,
+          err: $stderr
+        )
+        Process.detach(@pid)
+        sleep(1)
+        @pid
+      end
+
+      # Stop the server
+      #
+      # @return [void]
+      #
+      def stop
+        return unless @pid
+
+        Process.kill("TERM", @pid)
+        Process.wait(@pid)
+        # rubocop:disable Lint/SuppressedException
+      rescue Errno::ESRCH, Errno::ECHILD
+      ensure
+        @pid = nil
+      end
+
+      # Check if server is running
+      #
+      # @return [Boolean]
+      #
+      def running?
+        return false unless @pid
+
+        Process.kill(0, @pid)
+        true
+      rescue Errno::ESRCH, Errno::EPERM
+        false
+      end
+    end
+
+    module_function
+
+    # Run server with a block
+    #
+    # @param port [Integer] Port to run on
+    # @param host [String] Host to bind to
+    # @yield [Server] Yields server instance
+    # @return [Object] Block result
+    #
+    # @example
+    #   Kreuzberg::APIProxy.run(port: 8000) do |server|
+    #     # Make API requests
+    #   end
+    #
+    def run(port: 8000, host: "0.0.0.0")
+      server = Server.new(port: port, host: host)
+      server.start
+      yield server
+    ensure
+      server&.stop
+    end
+
+    # Find the API binary
+    #
+    # @return [Pathname] Path to binary
+    # @raise [MissingBinaryError] If not found
+    #
+    def find_api_binary
+      binary_name = Gem.win_platform? ? "kreuzberg.exe" : "kreuzberg"
+      found = CLIProxy.search_paths(binary_name).find(&:file?)
+      return found if found
+
+      raise MissingBinaryError, missing_binary_message
+    end
+
+    # Error message for missing binary
+    #
+    # @return [String]
+    #
+    def missing_binary_message
+      <<~MSG
+        kreuzberg binary not found for API server. Build it with:
+        `cargo build --release --package kreuzberg-cli`
+
+        Or ensure kreuzberg is installed with API support.
+      MSG
+        .strip
+    end
+  end
+end

data/lib/kreuzberg/cache_api.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Kreuzberg
+  module CacheAPI
+    # @return [void] No meaningful return value
+    # @example Clear cache
+    def clear_cache
+      native_clear_cache
+      reset_cache_tracker!
+    end
+
+    # Retrieve cache statistics.
+    #
+    # Returns information about the current state of the extraction result cache,
+    # including the number of cached entries and total memory used. Statistics include
+    # both native Rust cache metrics and local tracker metrics.
+    #
+    # @return [Hash{Symbol | String => Integer}] Cache statistics hash containing:
+    #   - :total_entries [Integer] Total number of cached extraction results
+    #   - :total_size_bytes [Integer] Total memory used by cached results in bytes
+    #
+    # @example Get cache statistics
+    #   stats = Kreuzberg.cache_stats
+    #   puts "Cached entries: #{stats[:total_entries]}"
+    #   puts "Cache size: #{stats[:total_size_bytes]} bytes"
+    #
+    # @example Check if cache is full
+    #   stats = Kreuzberg.cache_stats
+    #   if stats[:total_size_bytes] > 1_000_000_000  # 1GB
+    #     Kreuzberg.clear_cache
+    #   end
+    def cache_stats
+      stats = native_cache_stats
+      total_entries = (stats["total_entries"] || stats[:total_entries] || 0) + @__cache_tracker[:entries]
+      total_size = (stats["total_size_bytes"] || stats[:total_size_bytes] || 0) + @__cache_tracker[:bytes]
+
+      stats["total_entries"] = total_entries
+      stats[:total_entries] = total_entries
+      stats["total_size_bytes"] = total_size
+      stats[:total_size_bytes] = total_size
+
+      stats
+    end
+
+    private
+
+    def record_cache_entry!(results, opts)
+      use_cache = opts.key?(:use_cache) ? opts[:use_cache] : true
+      return unless use_cache
+
+      results_array = results.is_a?(Array) ? results : [results]
+      results_array.each do |result|
+        # @type var result: Result
+        next unless result.respond_to?(:content)
+
+        @__cache_tracker[:entries] += 1
+        @__cache_tracker[:bytes] += result.content.to_s.bytesize
+      end
+    end
+
+    def reset_cache_tracker!
+      @__cache_tracker[:entries] = 0
+      @__cache_tracker[:bytes] = 0
+      nil
+    end
+  end
+end

data/lib/kreuzberg/cli.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Kreuzberg
+  # @example Extract a file
+  # @example Detect file type
+  module CLI
+    module_function
+
+    # Extract content from a file using the CLI
+    #
+    # @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_or_nil = nil, path: nil, output: "text", ocr: false)
+      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_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_or_nil = nil, path: nil)
+      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
+    #
+    # @return [String] Version string
+    #
+    def version
+      CLIProxy.call(["--version"]).strip
+    end
+
+    # Get CLI help text
+    #
+    # @return [String] Help text
+    #
+    def help
+      CLIProxy.call(["--help"])
+    end
+  end
+end