activestorage-ocr 0.1.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 407f4e4098cfdf7804094b783efa4e9dd6a8ef18ede70a8bf571eae693a17fa7
-  data.tar.gz: 368ec4b42ffa94ca71e6b6df4677d0af87dadd9ab14bf95e57a44aa2904e6a2d
+  metadata.gz: 9ac32a71c542c906c4a3d29ab10e1592a2fd08e79914f447beaa4216b9f3e321
+  data.tar.gz: e89646596ca0d7662d48f61633744453153426518e7c509951d9da632ae42571
 SHA512:
-  metadata.gz: 8cf7e677131db26961ca31684f932f4aff67a85c3b16ba1bb460ec49b1e74f172e64bd1be777bd0a0620df8756c62bdc858d9409857e27da48eb166bc0735669
-  data.tar.gz: 25b5ae857880af8f0e3a11e4874f15896f4451685e8cae45a0dce2cf6e1c9a8b5ac15f89f1e80920fa9f2bd3ce8bfcfb9a62ef38d99e57b4c977de5b8d65b30c
+  metadata.gz: f18b15c1cdc22d5816cf5f7d3c6d2b0cb9b1f89a60f1f78f20f5e020a34e0ca98c5f97108aec75904be08ed84b84937d801d0b2e09415279f028e5f384db439c
+  data.tar.gz: cb1422a3f9b30b81a9336ca9c69cc76cef8e17d52dc68711587ca80f26ad525bd26c875e7a0cc7aaf9460101c126c2fd9424216951fdc74b4c6e7673b436e3a5

data/README.md

@@ -3,16 +3,18 @@
 [![CI](https://github.com/Cause-of-a-Kind/activestorage-ocr/actions/workflows/ci.yml/badge.svg)](https://github.com/Cause-of-a-Kind/activestorage-ocr/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-OCR for Rails Active Storage attachments, powered by Rust and [ocrs](https://github.com/robertknight/ocrs).
+OCR for Rails Active Storage attachments, powered by Rust.
 
 ## Overview
 
-`activestorage-ocr` provides optical character recognition (OCR) for files stored with Active Storage. It uses a high-performance Rust server with the pure-Rust `ocrs` OCR engine, eliminating the need for third-party OCR services or system-level dependencies.
+`activestorage-ocr` provides optical character recognition (OCR) for files stored with Active Storage. It uses a high-performance Rust server with your choice of OCR engine, eliminating the need for third-party OCR services.
 
 **Key Features:**
-- **Pure Rust** - No Tesseract or system dependencies required
-- **Self-contained** - Models download automatically on first run (~50MB)
-- **Fast** - Processes images in ~150ms
+- **Two OCR Engines** - Choose the right tool for the job:
+  - **ocrs** (default) - Pure Rust, zero system dependencies
+  - **leptess** - Tesseract-based, statically linked (no system Tesseract needed)
+- **Self-contained** - Pre-built binaries with no system dependencies
+- **Per-request engine selection** - Use different engines for different files
 - **Automatic** - OCR runs automatically when files are uploaded via Active Storage
 
 **Supported Formats:**
@@ -24,6 +26,24 @@ OCR for Rails Active Storage attachments, powered by Rust and [ocrs](https://git
 - **Ruby gem** provides seamless Rails integration
 - Simple HTTP/JSON protocol for easy debugging
 
+### Choosing an Engine
+
+| Engine | Binary Size | Notes |
+|--------|-------------|-------|
+| `ocrs` | ~9 MB | Pure Rust, modern neural network approach |
+| `leptess` | ~13 MB | Tesseract-based, well-established OCR engine |
+| `all` | ~15 MB | Includes both engines for comparison |
+
+**Which engine should I use?**
+
+Start with `ocrs` (the default). It works well for most documents and has a smaller binary. If results aren't satisfactory, try `leptess`—it uses Tesseract, a mature OCR engine that's been around for decades.
+
+Neither engine is universally better—performance varies by image. The `all` variant lets you compare both engines on your actual documents to see which works best for your use case.
+
+**Platform Support:**
+- **Linux (x86_64):** Fully supported
+- **macOS / Windows:** ocrs-only variant works; Tesseract variants require building from source
+
 ## Requirements
 
 - Ruby 3.2+
@@ -45,6 +65,18 @@ bundle install
 bin/rails activestorage_ocr:install
 ```
 
+By default, this installs the `ocrs` engine (~9 MB binary). To install with Tesseract support:
+
+```bash
+# Install both engines (recommended for comparing results)
+bin/rails activestorage_ocr:install variant=all
+
+# Or install only the Tesseract-based engine
+bin/rails activestorage_ocr:install variant=leptess
+```
+
+**No system dependencies required.** The Tesseract OCR engine and training data are statically linked into the binary.
+
 **3. Add the OCR server to your `Procfile.dev`:**
 
 ```procfile
@@ -111,6 +143,15 @@ result.confidence  # => 0.95
 
 # Extract text from an Active Storage attachment
 result = client.extract_text(document.file)
+
+# Per-request engine selection (requires all-engines variant)
+result = client.extract_text(document.file, engine: :ocrs)    # Pure Rust engine
+result = client.extract_text(document.file, engine: :leptess) # Tesseract engine
+
+# Compare engines side-by-side
+comparison = client.compare(document.file)
+comparison[:ocrs].confidence    # => 0.95
+comparison[:leptess].confidence # => 0.92
 ```
 
 ## Configuration
@@ -162,10 +203,11 @@ In your `Dockerfile`, run the generator during the build to install the binary:
 RUN bundle install
 
 # Install OCR server binary to bin/dist/
-RUN bundle exec rails activestorage_ocr:install path=./bin/dist
+# Use variant=all to include both ocrs and Tesseract engines (~15 MB)
+RUN bundle exec rails activestorage_ocr:install variant=all path=./bin/dist
 
-# Alternatively, run the full generator:
-# RUN bundle exec rails generate activestorage_ocr:install
+# Or for the smaller ocrs-only variant (~9 MB):
+# RUN bundle exec rails activestorage_ocr:install path=./bin/dist
 ```
 
 Use foreman to manage both processes:
@@ -261,6 +303,12 @@ bin/rails activestorage_ocr:health
 # Install the OCR server binary for your platform
 bin/rails activestorage_ocr:install
 
+# Install with Tesseract support (all-engines variant)
+bin/rails activestorage_ocr:install variant=all
+
+# Install to a custom path
+bin/rails activestorage_ocr:install variant=all path=./bin/dist
+
 # Start the OCR server (for manual testing)
 bin/rails activestorage_ocr:start
 
@@ -269,6 +317,9 @@ bin/rails activestorage_ocr:health
 
 # Show binary info (platform, path, version)
 bin/rails activestorage_ocr:info
+
+# Compare both OCR engines on a file
+bin/rails activestorage_ocr:compare file=/path/to/image.png
 ```
 
 ## API Endpoints
@@ -278,8 +329,10 @@ The Rust server exposes these HTTP endpoints:
 | Endpoint | Method | Description |
 |----------|--------|-------------|
 | `/health` | GET | Health check |
-| `/info` | GET | Server info and supported formats |
-| `/ocr` | POST | Extract text from uploaded file |
+| `/info` | GET | Server info, available engines, and supported formats |
+| `/ocr` | POST | Extract text using default engine |
+| `/ocr/ocrs` | POST | Extract text using ocrs engine |
+| `/ocr/leptess` | POST | Extract text using Tesseract engine |
 
 ### Example with curl
 
@@ -287,9 +340,16 @@ The Rust server exposes these HTTP endpoints:
 # Health check
 curl http://localhost:9292/health
 
-# OCR an image
+# Server info (shows available engines)
+curl http://localhost:9292/info
+
+# OCR with default engine
 curl -X POST http://localhost:9292/ocr \
   -F "file=@document.png;type=image/png"
+
+# OCR with specific engine (requires all-engines variant)
+curl -X POST http://localhost:9292/ocr/leptess \
+  -F "file=@document.png;type=image/png"
 ```
 
 ## Development
@@ -297,22 +357,38 @@ curl -X POST http://localhost:9292/ocr \
 ### Building from source
 
 ```bash
-# Build the Rust server
+# Build with default engine (ocrs only)
 cd rust
 cargo build --release
 
+# Build with all engines (ocrs + Tesseract)
+cargo build --release --features all-engines
+
+# Build with specific engine only
+cargo build --release --features engine-leptess
+
 # The binary will be at rust/target/release/activestorage-ocr-server
 ```
 
+For local development with a Rails app, you can install a locally-built binary:
+
+```bash
+# In your Rails app directory
+bin/rails activestorage_ocr:install source=/path/to/activestorage-ocr/rust/target/release/activestorage-ocr-server path=./bin/dist
+```
+
 ### Running tests
 
 ```bash
 # Ruby unit tests
 bundle exec rake test
 
-# Rust tests
+# Rust tests (default engine)
 cd rust && cargo test
 
+# Rust tests (all engines)
+cd rust && cargo test --features all-engines -- --test-threads=1
+
 # Integration tests (requires server running)
 cd rust && ./target/release/activestorage-ocr-server &
 cd test/sandbox && RAILS_ENV=test bin/rails test

data/lib/activestorage/ocr/analyzer.rb

@@ -15,6 +15,7 @@ module ActiveStorage
     # After analysis, blobs will have the following metadata:
     # * +ocr_text+ - The extracted text
     # * +ocr_confidence+ - Confidence score (0.0 to 1.0)
+    # * +ocr_engine+ - The OCR engine used ("ocrs" or "leptess")
     # * +ocr_processed_at+ - ISO 8601 timestamp
     #
     # == Example

data/lib/activestorage/ocr/binary.rb

@@ -20,11 +20,23 @@ module ActiveStorage
     # * linux-x86_64 (Linux x86_64)
     # * linux-aarch64 (Linux ARM64)
     #
+    # == Binary Variants
+    #
+    # * :ocrs - Pure Rust OCR engine only (~15MB, no system dependencies)
+    # * :leptess - Tesseract OCR engine only (~50-80MB, no system dependencies)
+    # * :all - Both engines included (~80-100MB)
+    #
     # == Usage
     #
-    #   # Install the binary for the current platform
+    #   # Install the default (ocrs) binary for the current platform
     #   ActiveStorage::Ocr::Binary.install!
     #
+    #   # Install the leptess variant
+    #   ActiveStorage::Ocr::Binary.install!(variant: :leptess)
+    #
+    #   # Install all-engines variant
+    #   ActiveStorage::Ocr::Binary.install!(variant: :all)
+    #
     #   # Check if binary is installed
     #   ActiveStorage::Ocr::Binary.installed?  # => true
     #
@@ -38,6 +50,22 @@ module ActiveStorage
       # Name of the server binary.
       BINARY_NAME = "activestorage-ocr-server"
 
+      # Available binary variants with their download suffix and descriptions.
+      VARIANTS = {
+        ocrs: {
+          suffix: "",
+          description: "Pure Rust OCR engine (fast, no system dependencies)"
+        },
+        leptess: {
+          suffix: "-leptess",
+          description: "Tesseract OCR engine (better for messy images)"
+        },
+        all: {
+          suffix: "-all",
+          description: "All OCR engines included"
+        }
+      }.freeze
+
       class << self
         # Detects the current platform.
         #
@@ -107,17 +135,47 @@ module ActiveStorage
           ActiveStorage::Ocr::VERSION
         end
 
-        # Returns the download URL for the current platform.
+        # Returns the download URL for the current platform and variant.
+        #
+        # ==== Parameters
+        #
+        # * +variant+ - The binary variant (:ocrs, :leptess, or :all)
         #
         # ==== Returns
         #
         # GitHub releases URL for the platform-specific tarball.
-        def download_url
+        def download_url(variant: :ocrs)
+          variant = variant.to_sym
+          validate_variant!(variant)
           tag = "v#{version}"
-          filename = "activestorage-ocr-server-#{platform}.tar.gz"
+          suffix = VARIANTS[variant][:suffix]
+          filename = "activestorage-ocr-server#{suffix}-#{platform}.tar.gz"
           "https://github.com/#{GITHUB_REPO}/releases/download/#{tag}/#{filename}"
         end
 
+        # Lists available binary variants.
+        #
+        # ==== Returns
+        #
+        # Array of variant names.
+        def available_variants
+          VARIANTS.keys
+        end
+
+        # Returns info about a specific variant.
+        #
+        # ==== Parameters
+        #
+        # * +variant+ - The variant name (:ocrs, :leptess, or :all)
+        #
+        # ==== Returns
+        #
+        # Hash with :suffix and :description keys.
+        def variant_info(variant)
+          validate_variant!(variant)
+          VARIANTS[variant]
+        end
+
         # Downloads and installs the binary.
         #
         # Downloads from GitHub releases and extracts to the specified directory.
@@ -126,6 +184,7 @@ module ActiveStorage
         #
         # * +force+ - If true, reinstalls even if already installed
         # * +path+ - Custom installation directory (defaults to gem's bin directory)
+        # * +variant+ - The binary variant to install (:ocrs, :leptess, or :all)
         #
         # ==== Returns
         #
@@ -134,7 +193,9 @@ module ActiveStorage
         # ==== Raises
         #
         # RuntimeError if the download fails.
-        def install!(force: false, path: nil)
+        # ArgumentError if an invalid variant is specified.
+        def install!(force: false, path: nil, variant: :ocrs)
+          validate_variant!(variant)
           target_dir = path || install_dir
           target_path = File.join(target_dir, BINARY_NAME)
 
@@ -145,15 +206,18 @@ module ActiveStorage
 
           FileUtils.mkdir_p(target_dir)
 
-          puts "Downloading activestorage-ocr-server for #{platform}..."
+          variant_desc = VARIANTS[variant][:description]
+          puts "Downloading activestorage-ocr-server (#{variant_desc}) for #{platform}..."
 
-          uri = URI(download_url)
+          url = download_url(variant: variant)
+          uri = URI(url)
           response = fetch_with_redirects(uri)
 
           unless response.is_a?(Net::HTTPSuccess)
+            feature_flag = variant == :ocrs ? "engine-ocrs" : (variant == :leptess ? "engine-leptess" : "all-engines")
             raise "Failed to download binary: #{response.code} #{response.message}\n" \
-                  "URL: #{download_url}\n" \
-                  "You may need to build from source: cd rust && cargo build --release"
+                  "URL: #{url}\n" \
+                  "You may need to build from source: cd rust && cargo build --release --features #{feature_flag}"
           end
 
           extract_binary(response.body, target_path)
@@ -163,6 +227,18 @@ module ActiveStorage
 
         private
 
+        # Validates the variant parameter.
+        #
+        # ==== Raises
+        #
+        # ArgumentError if the variant is not valid.
+        def validate_variant!(variant)
+          variant = variant.to_sym
+          unless VARIANTS.key?(variant)
+            raise ArgumentError, "Invalid variant: #{variant}. Valid variants: #{VARIANTS.keys.join(', ')}"
+          end
+        end
+
         # Fetches a URL, following redirects.
         def fetch_with_redirects(uri, limit = 10)
           raise "Too many redirects" if limit == 0

data/lib/activestorage/ocr/client.rb

@@ -17,6 +17,12 @@ module ActiveStorage
     #   # Extract text from a file path
     #   result = client.extract_text_from_path("/path/to/image.png")
     #
+    #   # Use a specific OCR engine
+    #   result = client.extract_text(document.file, engine: :leptess)
+    #
+    #   # Compare results from both engines
+    #   comparison = client.compare(document.file)
+    #
     #   # Check server health
     #   client.healthy?  # => true
     #
@@ -37,6 +43,9 @@ module ActiveStorage
       # ==== Parameters
       #
       # * +blob+ - An ActiveStorage::Blob instance
+      # * +engine+ - OCR engine to use (:ocrs or :leptess). Defaults to configured engine.
+      # * +preprocess+ - Preprocessing preset (:none, :minimal, :default, :aggressive).
+      #                  Defaults to configured preset.
       #
       # ==== Returns
       #
@@ -46,9 +55,9 @@ module ActiveStorage
       #
       # * ConnectionError - if the server is unreachable
       # * ServerError - if the server returns an error
-      def extract_text(blob)
+      def extract_text(blob, engine: nil, preprocess: nil)
         blob.open do |file|
-          extract_text_from_file(file, blob.content_type, blob.filename.to_s)
+          extract_text_from_file(file, blob.content_type, blob.filename.to_s, engine: engine, preprocess: preprocess)
         end
       end
 
@@ -59,6 +68,9 @@ module ActiveStorage
       # * +path+ - Path to the file
       # * +content_type+ - MIME type (auto-detected if not provided)
       # * +filename+ - Filename to send (defaults to basename of path)
+      # * +engine+ - OCR engine to use (:ocrs or :leptess). Defaults to configured engine.
+      # * +preprocess+ - Preprocessing preset (:none, :minimal, :default, :aggressive).
+      #                  Defaults to configured preset.
       #
       # ==== Returns
       #
@@ -68,12 +80,12 @@ module ActiveStorage
       #
       # * ConnectionError - if the server is unreachable
       # * ServerError - if the server returns an error
-      def extract_text_from_path(path, content_type: nil, filename: nil)
+      def extract_text_from_path(path, content_type: nil, filename: nil, engine: nil, preprocess: nil)
         content_type ||= Marcel::MimeType.for(Pathname.new(path))
         filename ||= File.basename(path)
 
         File.open(path, "rb") do |file|
-          extract_text_from_file(file, content_type, filename)
+          extract_text_from_file(file, content_type, filename, engine: engine, preprocess: preprocess)
         end
       end
 
@@ -86,6 +98,9 @@ module ActiveStorage
       # * +file+ - An IO object (File, StringIO, etc.)
       # * +content_type+ - MIME type of the file
       # * +filename+ - Filename to send to the server
+      # * +engine+ - OCR engine to use (:ocrs or :leptess). Defaults to configured engine.
+      # * +preprocess+ - Preprocessing preset (:none, :minimal, :default, :aggressive).
+      #                  Defaults to configured preset.
       #
       # ==== Returns
       #
@@ -95,8 +110,12 @@ module ActiveStorage
       #
       # * ConnectionError - if the server is unreachable
       # * ServerError - if the server returns an error
-      def extract_text_from_file(file, content_type, filename)
-        response = connection.post("/ocr") do |req|
+      def extract_text_from_file(file, content_type, filename, engine: nil, preprocess: nil)
+        target_engine = engine || @config.engine
+        target_preprocess = preprocess || @config.preprocess
+        endpoint = ocr_endpoint_for(target_engine, target_preprocess)
+
+        response = connection.post(endpoint) do |req|
           req.body = {
             file: Faraday::Multipart::FilePart.new(
               file,
@@ -111,6 +130,57 @@ module ActiveStorage
         raise ConnectionError, "Failed to connect to OCR server: #{e.message}"
       end
 
+      # Compares OCR results from both engines.
+      #
+      # Runs OCR on the same file using both ocrs and leptess engines,
+      # allowing you to compare accuracy and performance.
+      #
+      # ==== Parameters
+      #
+      # * +blob+ - An ActiveStorage::Blob instance
+      #
+      # ==== Returns
+      #
+      # A Hash with :ocrs and :leptess keys, each containing a Result object.
+      #
+      # ==== Raises
+      #
+      # * ConnectionError - if the server is unreachable
+      # * ServerError - if the server returns an error
+      def compare(blob)
+        ocrs_result = extract_text(blob, engine: :ocrs)
+        leptess_result = extract_text(blob, engine: :leptess)
+
+        {
+          ocrs: ocrs_result,
+          leptess: leptess_result
+        }
+      end
+
+      # Compares OCR results from both engines using a file path.
+      #
+      # ==== Parameters
+      #
+      # * +path+ - Path to the file
+      # * +content_type+ - MIME type (auto-detected if not provided)
+      # * +filename+ - Filename to send (defaults to basename of path)
+      #
+      # ==== Returns
+      #
+      # A Hash with :ocrs and :leptess keys, each containing a Result object.
+      def compare_from_path(path, content_type: nil, filename: nil)
+        content_type ||= Marcel::MimeType.for(Pathname.new(path))
+        filename ||= File.basename(path)
+
+        ocrs_result = extract_text_from_path(path, content_type: content_type, filename: filename, engine: :ocrs)
+        leptess_result = extract_text_from_path(path, content_type: content_type, filename: filename, engine: :leptess)
+
+        {
+          ocrs: ocrs_result,
+          leptess: leptess_result
+        }
+      end
+
       # Checks if the OCR server is healthy.
       #
       # ==== Returns
@@ -143,6 +213,29 @@ module ActiveStorage
 
       private
 
+      # Returns the OCR endpoint path for the given engine and preprocess preset.
+      #
+      # ==== Parameters
+      #
+      # * +engine+ - Engine name (:ocrs or :leptess)
+      # * +preprocess+ - Preprocessing preset (:none, :minimal, :default, :aggressive)
+      #
+      # ==== Returns
+      #
+      # The endpoint path string with query parameter (e.g., "/ocr?preprocess=default")
+      def ocr_endpoint_for(engine, preprocess)
+        base = case engine.to_sym
+               when :ocrs
+                 "/ocr"
+               when :leptess
+                 "/ocr/leptess"
+               else
+                 raise ArgumentError, "Unknown engine: #{engine}"
+               end
+
+        "#{base}?preprocess=#{preprocess}"
+      end
+
       # Returns the Faraday connection, creating it if necessary.
       def connection
         @connection ||= Faraday.new(url: @config.server_url) do |f|
@@ -166,7 +259,9 @@ module ActiveStorage
           text: data[:text],
           confidence: data[:confidence],
           processing_time_ms: data[:processing_time_ms],
-          warnings: data[:warnings] || []
+          warnings: data[:warnings] || [],
+          engine: data[:engine],
+          preprocessing: data[:preprocessing]
         )
       end
     end

data/lib/activestorage/ocr/configuration.rb

@@ -9,6 +9,8 @@ module ActiveStorage
     #   ActiveStorage::Ocr.configure do |config|
     #     config.server_url = "http://localhost:9292"
     #     config.timeout = 60
+    #     config.engine = :leptess  # Use Tesseract engine instead of default ocrs
+    #     config.preprocess = :aggressive  # Use aggressive preprocessing
     #   end
     #
     # == Environment Variables
@@ -16,8 +18,16 @@ module ActiveStorage
     # * +ACTIVESTORAGE_OCR_SERVER_URL+ - OCR server URL (default: http://localhost:9292)
     # * +ACTIVESTORAGE_OCR_TIMEOUT+ - Request timeout in seconds (default: 30)
     # * +ACTIVESTORAGE_OCR_OPEN_TIMEOUT+ - Connection timeout in seconds (default: 5)
+    # * +ACTIVESTORAGE_OCR_ENGINE+ - OCR engine to use: ocrs (default) or leptess
+    # * +ACTIVESTORAGE_OCR_PREPROCESS+ - Preprocessing preset: none, minimal, default, aggressive
     #
     class Configuration
+      # Valid OCR engine names
+      VALID_ENGINES = %i[ocrs leptess].freeze
+
+      # Valid preprocessing preset names
+      VALID_PREPROCESS = %i[none minimal default aggressive].freeze
+
       # The URL of the OCR server.
       attr_accessor :server_url
 
@@ -30,6 +40,16 @@ module ActiveStorage
       # Array of MIME types that the analyzer will process.
       attr_accessor :content_types
 
+      # The OCR engine to use (:ocrs or :leptess).
+      # Default is :ocrs (pure Rust, no dependencies).
+      # Use :leptess for Tesseract-based OCR (better for messy images).
+      attr_reader :engine
+
+      # The preprocessing preset to use (:none, :minimal, :default, :aggressive).
+      # Default is :default.
+      # Use :none to skip preprocessing, :aggressive for poor quality images.
+      attr_reader :preprocess
+
       # Creates a new Configuration with default values.
       #
       # Defaults are read from environment variables if set.
@@ -38,6 +58,45 @@ module ActiveStorage
         @timeout = ENV.fetch("ACTIVESTORAGE_OCR_TIMEOUT", 30).to_i
         @open_timeout = ENV.fetch("ACTIVESTORAGE_OCR_OPEN_TIMEOUT", 5).to_i
         @content_types = default_content_types
+        self.engine = ENV.fetch("ACTIVESTORAGE_OCR_ENGINE", "ocrs").to_sym
+        self.preprocess = ENV.fetch("ACTIVESTORAGE_OCR_PREPROCESS", "default").to_sym
+      end
+
+      # Set the OCR engine to use.
+      #
+      # ==== Parameters
+      #
+      # * +value+ - Engine name (:ocrs or :leptess)
+      #
+      # ==== Raises
+      #
+      # * +ArgumentError+ if an invalid engine name is provided
+      def engine=(value)
+        value = value.to_sym
+        unless VALID_ENGINES.include?(value)
+          raise ArgumentError, "Invalid engine: #{value}. Valid engines: #{VALID_ENGINES.join(', ')}"
+        end
+
+        @engine = value
+      end
+
+      # Set the preprocessing preset to use.
+      #
+      # ==== Parameters
+      #
+      # * +value+ - Preset name (:none, :minimal, :default, :aggressive)
+      #
+      # ==== Raises
+      #
+      # * +ArgumentError+ if an invalid preset name is provided
+      def preprocess=(value)
+        value = value.to_sym
+        unless VALID_PREPROCESS.include?(value)
+          raise ArgumentError,
+                "Invalid preprocess preset: #{value}. Valid presets: #{VALID_PREPROCESS.join(', ')}"
+        end
+
+        @preprocess = value
       end
 
       # Returns the default list of supported content types.

data/lib/activestorage/ocr/railtie.rb

@@ -13,6 +13,7 @@ module ActiveStorage
     # * +activestorage_ocr:start+ - Start the OCR server
     # * +activestorage_ocr:health+ - Check if the server is responding
     # * +activestorage_ocr:info+ - Show binary and platform information
+    # * +activestorage_ocr:compare+ - Compare OCR results from different engines
     #
     class Railtie < Rails::Railtie
       # Registers the OCR analyzer with Active Storage.
@@ -29,10 +30,23 @@ module ActiveStorage
       # Defines rake tasks for server management.
       rake_tasks do
         namespace :activestorage_ocr do
-          desc "Install the OCR server binary (optional: path=./bin/dist)"
+          desc "Install the OCR server binary (variant=ocrs|leptess|all, path=./bin/dist, source=local_binary_path)"
           task :install do
             path = ENV["path"]
-            ActiveStorage::Ocr::Binary.install!(path: path)
+            variant = (ENV["variant"] || "ocrs").to_sym
+            source = ENV["source"]
+
+            if source
+              # Local development: copy from a local path instead of downloading
+              target_dir = path || ActiveStorage::Ocr::Binary.install_dir
+              target_path = File.join(target_dir, ActiveStorage::Ocr::Binary::BINARY_NAME)
+              FileUtils.mkdir_p(target_dir)
+              FileUtils.cp(source, target_path)
+              FileUtils.chmod(0o755, target_path)
+              puts "Copied #{source} to #{target_path}"
+            else
+              ActiveStorage::Ocr::Binary.install!(path: path, variant: variant)
+            end
           end
 
           desc "Check OCR server health"
@@ -42,7 +56,11 @@ module ActiveStorage
               puts "OCR server is healthy"
               info = client.server_info
               puts "  Version: #{info[:version]}"
-              puts "  Supported formats: #{info[:supported_formats].join(', ')}"
+              puts "  Default engine: #{info[:default_engine]}"
+              puts "  Available engines:"
+              info[:available_engines].each do |engine|
+                puts "    - #{engine[:name]}: #{engine[:description]}"
+              end
             else
               puts "OCR server is not responding"
               exit 1
@@ -54,7 +72,8 @@ module ActiveStorage
             binary = ActiveStorage::Ocr::Binary.binary_path
             unless File.executable?(binary)
               puts "Binary not found. Installing..."
-              ActiveStorage::Ocr::Binary.install!
+              variant = (ENV["variant"] || "ocrs").to_sym
+              ActiveStorage::Ocr::Binary.install!(variant: variant)
             end
 
             config = ActiveStorage::Ocr.configuration
@@ -72,6 +91,59 @@ module ActiveStorage
             puts "Binary path: #{ActiveStorage::Ocr::Binary.binary_path}"
             puts "Installed: #{ActiveStorage::Ocr::Binary.installed?}"
             puts "Version: #{ActiveStorage::Ocr::Binary.version}"
+            puts ""
+            puts "Available variants:"
+            ActiveStorage::Ocr::Binary::VARIANTS.each do |name, info|
+              puts "  #{name}: #{info[:description]}"
+            end
+          end
+
+          desc "Compare OCR engines on a file (file=/path/to/image.png)"
+          task compare: :environment do
+            file_path = ENV["file"]
+            unless file_path
+              puts "Usage: rake activestorage_ocr:compare file=/path/to/image.png"
+              exit 1
+            end
+
+            unless File.exist?(file_path)
+              puts "File not found: #{file_path}"
+              exit 1
+            end
+
+            client = ActiveStorage::Ocr::Client.new
+            puts "Comparing OCR engines on: #{file_path}"
+            puts ""
+
+            begin
+              comparison = client.compare_from_path(file_path)
+
+              comparison.each do |engine, result|
+                puts "#{engine.to_s.upcase}:"
+                puts "  Text length: #{result.text.length} characters"
+                puts "  Confidence: #{(result.confidence * 100).round(1)}%"
+                puts "  Processing time: #{result.processing_time_ms}ms"
+                if result.warnings.any?
+                  puts "  Warnings: #{result.warnings.join(', ')}"
+                end
+                puts ""
+              end
+
+              # Summary
+              faster = comparison.min_by { |_, r| r.processing_time_ms }
+              higher_conf = comparison.max_by { |_, r| r.confidence }
+              puts "Summary:"
+              puts "  Faster engine: #{faster[0]} (#{faster[1].processing_time_ms}ms)"
+              puts "  Higher confidence: #{higher_conf[0]} (#{(higher_conf[1].confidence * 100).round(1)}%)"
+            rescue ActiveStorage::Ocr::ConnectionError => e
+              puts "Error: #{e.message}"
+              puts "Make sure the OCR server is running with both engines enabled."
+              exit 1
+            rescue ActiveStorage::Ocr::ServerError => e
+              puts "Server error: #{e.message}"
+              puts "This engine may not be available. Check server configuration."
+              exit 1
+            end
           end
         end
       end

data/lib/activestorage/ocr/result.rb

@@ -27,6 +27,13 @@ module ActiveStorage
       # Array of warning messages from the OCR server.
       attr_reader :warnings
 
+      # The OCR engine that processed this result (e.g., "ocrs" or "leptess").
+      attr_reader :engine
+
+      # Preprocessing statistics (Hash with :preset, :total_time_ms, :steps).
+      # nil if preprocessing was skipped.
+      attr_reader :preprocessing
+
       # Creates a new Result.
       #
       # ==== Parameters
@@ -35,11 +42,15 @@ module ActiveStorage
       # * +confidence+ - Confidence score (0.0 to 1.0)
       # * +processing_time_ms+ - Processing time in milliseconds
       # * +warnings+ - Array of warning messages (optional)
-      def initialize(text:, confidence:, processing_time_ms:, warnings: [])
+      # * +engine+ - The OCR engine used (optional)
+      # * +preprocessing+ - Preprocessing stats hash (optional)
+      def initialize(text:, confidence:, processing_time_ms:, warnings: [], engine: nil, preprocessing: nil)
         @text = text
         @confidence = confidence
         @processing_time_ms = processing_time_ms
         @warnings = warnings
+        @engine = engine
+        @preprocessing = preprocessing
       end
 
       # Returns whether OCR successfully extracted text.
@@ -51,6 +62,16 @@ module ActiveStorage
         !text.nil? && !text.empty?
       end
 
+      # Returns the preprocessing time in milliseconds, or 0 if not preprocessed.
+      def preprocessing_time_ms
+        preprocessing&.dig(:total_time_ms) || 0
+      end
+
+      # Returns the preprocessing preset used, or nil if not preprocessed.
+      def preprocessing_preset
+        preprocessing&.dig(:preset)
+      end
+
       # Converts the result to a Hash.
       #
       # ==== Returns
@@ -61,7 +82,9 @@ module ActiveStorage
           text: text,
           confidence: confidence,
           processing_time_ms: processing_time_ms,
-          warnings: warnings
+          warnings: warnings,
+          engine: engine,
+          preprocessing: preprocessing
         }
       end
 
@@ -71,11 +94,12 @@ module ActiveStorage
       #
       # ==== Returns
       #
-      # A Hash with +:ocr_text+, +:ocr_confidence+, and +:ocr_processed_at+.
+      # A Hash with +:ocr_text+, +:ocr_confidence+, +:ocr_engine+, and +:ocr_processed_at+.
       def to_metadata
         {
           ocr_text: text,
           ocr_confidence: confidence,
+          ocr_engine: engine,
           ocr_processed_at: Time.now.utc.iso8601
         }
       end

data/lib/activestorage/ocr/version.rb

@@ -2,6 +2,6 @@
 
 module ActiveStorage
   module Ocr
-    VERSION = "0.1.2"
+    VERSION = "0.3.0"
   end
 end

data/lib/activestorage/ocr.rb

@@ -19,14 +19,20 @@ module ActiveStorage
   # OCR support for Rails Active Storage attachments.
   #
   # This module provides optical character recognition (OCR) for files stored
-  # with Active Storage using a high-performance Rust server with the pure-Rust
-  # +ocrs+ OCR engine.
+  # with Active Storage using a high-performance Rust server.
+  #
+  # == OCR Engines
+  #
+  # Two engines are available:
+  # * +:ocrs+ - Pure Rust engine (default). Fast, no system dependencies.
+  # * +:leptess+ - Tesseract-based engine. Better for noisy/messy images.
   #
   # == Configuration
   #
   #   ActiveStorage::Ocr.configure do |config|
   #     config.server_url = "http://localhost:9292"
   #     config.timeout = 30
+  #     config.engine = :leptess  # Use Tesseract instead of default ocrs
   #   end
   #
   # == Basic Usage
@@ -35,6 +41,16 @@ module ActiveStorage
   #   result = ActiveStorage::Ocr.extract_text(document.file)
   #   result.text        # => "Extracted text..."
   #   result.confidence  # => 0.95
+  #   result.engine      # => "ocrs"
+  #
+  #   # Use a specific engine for one request
+  #   client = ActiveStorage::Ocr::Client.new
+  #   result = client.extract_text(document.file, engine: :leptess)
+  #
+  #   # Compare both engines
+  #   comparison = client.compare(document.file)
+  #   comparison[:ocrs].text      # => "Text from ocrs..."
+  #   comparison[:leptess].text   # => "Text from leptess..."
   #
   # == Error Handling
   #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activestorage-ocr
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Michael Rispoli