activestorage-ocr 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c2944589a15452bdc9189df16529baf298e7db1d39898c6a127558dd8e55e58a
-  data.tar.gz: bc222d478d3c122f1bdba2e0f7a8b58893a9c0581ec86d06c2c8025410d36a20
+  metadata.gz: 77f12aaeaf8f89365fc3e7789d375af8ac5fdc8920c4dd6ecff838e8268a6264
+  data.tar.gz: 5d9a43201af05e03469bf61d7b6bd9b77aec2ffb489073a9c768dba0638ad2fb
 SHA512:
-  metadata.gz: b6569b0027e7976cb5afa6cf45294eb1680e7f6f769be27db98794f64cf5079f6254587f56b70adcb72a033b566bb6836879b7563fab18470b15ec7434b215b5
-  data.tar.gz: 45839fed9f4f618c50246c89f7acc3345a3c57d52a07c348fed17420bbb465ecf883f6d1b711f1b33ea57a35975995cdbe8ab26c1486ade6267778a34db8cf59
+  metadata.gz: 9e4858ee78b144076beade1a20a7458ad478149937993a8cd1a1e82c9af13cbced8c6c4686fc2bdf2d722747830572566166a0dd1afd74c535021b97407f2d88
+  data.tar.gz: 24ea227e389f377a192f5efd533f410fc1cd09b7adf3e322b555334ac770f36cf4d94fb5fffae602b66560991a39c41f79ca18ed9e271657b28dbc3181f5e3f6

data/README.md

@@ -3,17 +3,19 @@
 [![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
-- **HTTP/JSON API** - Easy to debug and integrate
+- **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:**
 - Images: PNG, JPEG, TIFF, WebP, GIF, BMP
@@ -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+
@@ -32,53 +52,116 @@ OCR for Rails Active Storage attachments, powered by Rust and [ocrs](https://git
 
 ## Installation
 
-Add to your Gemfile:
+**1. Add to your Gemfile:**
 
 ```ruby
 gem "activestorage-ocr"
 ```
 
-Then install the OCR server binary:
+**2. Install the gem and OCR server binary:**
 
 ```bash
 bundle install
 bin/rails activestorage_ocr:install
 ```
 
-## Quick Start
+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
+web: bin/rails server
+ocr: activestorage-ocr-server --host 127.0.0.1 --port 9292
+```
+
+Now when you run `bin/dev`, the OCR server starts automatically alongside Rails.
+
+> **Note:** If you don't have a `Procfile.dev`, create one. Rails 7+ apps typically use `bin/dev` with [foreman](https://github.com/ddollar/foreman) or [overmind](https://github.com/DarthSim/overmind) to manage multiple processes.
+
+## Usage
+
+Once installed, OCR happens **automatically** when you upload images or PDFs through Active Storage. The extracted text is stored in the blob's metadata.
+
+### Accessing OCR Results
+
+```ruby
+# After uploading a file
+document.file.analyze  # Triggers OCR (usually happens automatically)
+
+# Access the results from metadata
+document.file.metadata["ocr_text"]         # => "Extracted text..."
+document.file.metadata["ocr_confidence"]   # => 0.85
+document.file.metadata["ocr_processed_at"] # => "2024-12-24T12:00:00Z"
+```
+
+### Helper Methods (Optional)
+
+Add convenience methods to your model:
+
+```ruby
+class Document < ApplicationRecord
+  has_one_attached :file
+
+  def ocr_text
+    file.metadata["ocr_text"]
+  end
+
+  def ocr_confidence
+    file.metadata["ocr_confidence"]
+  end
+
+  def ocr_processed?
+    file.metadata["ocr_processed_at"].present?
+  end
+end
+```
+
+### Using the Client Directly
 
-1. **Start the OCR server:**
+You can also use the client directly for more control:
 
-   ```bash
-   bin/rails activestorage_ocr:start
-   ```
+```ruby
+client = ActiveStorage::Ocr::Client.new
 
-2. **Use the client in your Rails app:**
+# Check server health
+client.healthy?  # => true
 
-   ```ruby
-   # In rails console or your code
-   client = ActiveStorage::Ocr::Client.new
+# Extract text from a file path
+result = client.extract_text_from_path("/path/to/image.png")
+result.text        # => "Extracted text..."
+result.confidence  # => 0.95
 
-   # Check server health
-   client.healthy?  # => true
+# Extract text from an Active Storage attachment
+result = client.extract_text(document.file)
 
-   # Extract text from a file
-   result = client.extract_text_from_path("/path/to/image.png", content_type: "image/png")
-   result.text        # => "Extracted text..."
-   result.confidence  # => 0.95
+# 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
 
-   # Extract text from an Active Storage attachment
-   result = client.extract_text(document.file)
-   ```
+# Compare engines side-by-side
+comparison = client.compare(document.file)
+comparison[:ocrs].confidence    # => 0.95
+comparison[:leptess].confidence # => 0.92
+```
 
 ## Configuration
 
 ```ruby
 # config/initializers/activestorage_ocr.rb
 ActiveStorage::Ocr.configure do |config|
-  config.server_host = "127.0.0.1"
-  config.server_port = 9292
-  config.timeout = 60
+  config.server_url = ENV.fetch("ACTIVESTORAGE_OCR_SERVER_URL", "http://127.0.0.1:9292")
+  config.timeout = 60        # Request timeout in seconds
+  config.open_timeout = 10   # Connection timeout in seconds
 end
 ```
 
@@ -86,8 +169,133 @@ end
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `ACTIVESTORAGE_OCR_HOST` | `127.0.0.1` | Server host |
-| `ACTIVESTORAGE_OCR_PORT` | `9292` | Server port |
+| `ACTIVESTORAGE_OCR_SERVER_URL` | `http://127.0.0.1:9292` | Full URL to the OCR server |
+
+## Production Deployment
+
+For production deployments, the OCR server binary needs to be installed in your app's `bin/` directory (not the gem directory) so it can be referenced from your Procfile.
+
+### Setup for Production
+
+**1. Run the install generator:**
+
+```bash
+rails generate activestorage_ocr:install
+```
+
+This creates:
+- `bin/activestorage-ocr-server` - A wrapper script that runs the OCR server
+- `bin/dist/activestorage-ocr-server` - The actual binary (gitignored)
+
+**2. Add to your Procfile:**
+
+```procfile
+web: bundle exec puma -C config/puma.rb
+ocr: bin/activestorage-ocr-server --host 127.0.0.1 --port 9292
+```
+
+### Docker Deployment
+
+In your `Dockerfile`, run the generator during the build to install the binary:
+
+```dockerfile
+# Install gems
+RUN bundle install
+
+# Install OCR server binary to 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
+
+# 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:
+
+```dockerfile
+# Procfile
+CMD ["bundle", "exec", "foreman", "start"]
+```
+
+### Fly.io Deployment
+
+**fly.toml configuration:**
+
+```toml
+app = "your-app-name"
+primary_region = "iad"
+
+[deploy]
+  # Note: Don't use release_command for SQLite with volumes
+  # Migrations run in docker-entrypoint instead
+
+[env]
+  RAILS_ENV = "production"
+  ACTIVESTORAGE_OCR_SERVER_URL = "http://127.0.0.1:9292"
+
+[http_service]
+  internal_port = 8080
+  force_https = true
+
+[[mounts]]
+  source = "data"
+  destination = "/rails/storage"
+
+[[vm]]
+  memory = "1024mb"
+  cpu_kind = "shared"
+  cpus = 2
+```
+
+**Procfile for Fly.io:**
+
+```procfile
+web: bundle exec puma -C config/puma.rb
+ocr: bin/activestorage-ocr-server --host 127.0.0.1 --port 9292
+```
+
+**Important notes for Fly.io:**
+- Use `foreman` as the entrypoint to run both processes
+- The OCR server binds to `127.0.0.1` (internal only)
+- Set `ACTIVESTORAGE_OCR_SERVER_URL` env var to `http://127.0.0.1:9292`
+- For SQLite with volumes, run migrations in `docker-entrypoint` not `release_command`
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ACTIVESTORAGE_OCR_SERVER_URL` | `http://127.0.0.1:9292` | URL where the OCR server is running |
+| `ACTIVESTORAGE_OCR_TIMEOUT` | `30` | Request timeout in seconds |
+| `ACTIVESTORAGE_OCR_OPEN_TIMEOUT` | `5` | Connection timeout in seconds |
+
+### Troubleshooting
+
+**Binary not found:**
+```
+Error: bin/activestorage-ocr-server: No such file or directory
+```
+Solution: Run `rails generate activestorage_ocr:install` or `rails activestorage_ocr:install path=./bin/dist`
+
+**Connection refused:**
+```
+Faraday::ConnectionFailed: Connection refused
+```
+Solution: Ensure the OCR server is running and `ACTIVESTORAGE_OCR_SERVER_URL` is correctly configured.
+
+**Timeout errors:**
+```
+Faraday::TimeoutError
+```
+Solution: Increase timeout values in the initializer or reduce image/PDF sizes.
+
+**Health check:**
+```bash
+# Verify the OCR server is responding
+curl http://localhost:9292/health
+
+# Or via rake task
+bin/rails activestorage_ocr:health
+```
 
 ## Rake Tasks
 
@@ -95,7 +303,13 @@ end
 # Install the OCR server binary for your platform
 bin/rails activestorage_ocr:install
 
-# Start the OCR server
+# 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
 
 # Check server health
@@ -103,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
@@ -112,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
 
@@ -121,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
@@ -131,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,24 +135,56 @@ 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 gem's bin directory.
+        # Downloads from GitHub releases and extracts to the specified directory.
         #
         # ==== Parameters
         #
         # * +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
         #
@@ -133,27 +193,52 @@ module ActiveStorage
         # ==== Raises
         #
         # RuntimeError if the download fails.
-        def install!(force: false)
-          return binary_path if installed? && !force
+        # 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)
+
+          if !force && File.executable?(target_path)
+            puts "Binary already installed at #{target_path}"
+            return target_path
+          end
 
-          puts "Downloading activestorage-ocr-server for #{platform}..."
+          FileUtils.mkdir_p(target_dir)
 
-          uri = URI(download_url)
+          variant_desc = VARIANTS[variant][:description]
+          puts "Downloading activestorage-ocr-server (#{variant_desc}) for #{platform}..."
+
+          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)
-          puts "Installed to #{binary_path}"
-          binary_path
+          extract_binary(response.body, target_path)
+          puts "Installed to #{target_path}"
+          target_path
         end
 
         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
@@ -174,17 +259,17 @@ module ActiveStorage
         end
 
         # Extracts the binary from a gzipped tarball.
-        def extract_binary(tarball_data)
+        def extract_binary(tarball_data, target_path)
           gz = Zlib::GzipReader.new(StringIO.new(tarball_data))
           tar = Gem::Package::TarReader.new(gz)
 
           tar.each do |entry|
             next unless entry.file? && entry.full_name == BINARY_NAME
 
-            File.open(binary_path, "wb") do |f|
+            File.open(target_path, "wb") do |f|
               f.write(entry.read)
             end
-            File.chmod(0o755, binary_path)
+            File.chmod(0o755, target_path)
             return
           end
 

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,7 @@ module ActiveStorage
       # ==== Parameters
       #
       # * +blob+ - An ActiveStorage::Blob instance
+      # * +engine+ - OCR engine to use (:ocrs or :leptess). Defaults to configured engine.
       #
       # ==== Returns
       #
@@ -46,9 +53,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)
         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)
         end
       end
 
@@ -59,6 +66,7 @@ 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.
       #
       # ==== Returns
       #
@@ -68,12 +76,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)
         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)
         end
       end
 
@@ -86,6 +94,7 @@ 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.
       #
       # ==== Returns
       #
@@ -95,8 +104,11 @@ 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)
+        target_engine = engine || @config.engine
+        endpoint = ocr_endpoint_for(target_engine)
+
+        response = connection.post(endpoint) do |req|
           req.body = {
             file: Faraday::Multipart::FilePart.new(
               file,
@@ -111,6 +123,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 +206,26 @@ module ActiveStorage
 
       private
 
+      # Returns the OCR endpoint path for the given engine.
+      #
+      # ==== Parameters
+      #
+      # * +engine+ - Engine name (:ocrs or :leptess)
+      #
+      # ==== Returns
+      #
+      # The endpoint path string (e.g., "/ocr" or "/ocr/leptess")
+      def ocr_endpoint_for(engine)
+        case engine.to_sym
+        when :ocrs
+          "/ocr"
+        when :leptess
+          "/ocr/leptess"
+        else
+          raise ArgumentError, "Unknown engine: #{engine}"
+        end
+      end
+
       # Returns the Faraday connection, creating it if necessary.
       def connection
         @connection ||= Faraday.new(url: @config.server_url) do |f|
@@ -166,7 +249,8 @@ module ActiveStorage
           text: data[:text],
           confidence: data[:confidence],
           processing_time_ms: data[:processing_time_ms],
-          warnings: data[:warnings] || []
+          warnings: data[:warnings] || [],
+          engine: data[:engine]
         )
       end
     end

data/lib/activestorage/ocr/configuration.rb

@@ -9,6 +9,7 @@ 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
     #   end
     #
     # == Environment Variables
@@ -16,8 +17,12 @@ 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
     #
     class Configuration
+      # Valid OCR engine names
+      VALID_ENGINES = %i[ocrs leptess].freeze
+
       # The URL of the OCR server.
       attr_accessor :server_url
 
@@ -30,6 +35,11 @@ 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
+
       # Creates a new Configuration with default values.
       #
       # Defaults are read from environment variables if set.
@@ -38,6 +48,25 @@ 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
+      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
 
       # 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,9 +30,23 @@ module ActiveStorage
       # Defines rake tasks for server management.
       rake_tasks do
         namespace :activestorage_ocr do
-          desc "Install the OCR server binary"
+          desc "Install the OCR server binary (variant=ocrs|leptess|all, path=./bin/dist, source=local_binary_path)"
           task :install do
-            ActiveStorage::Ocr::Binary.install!
+            path = ENV["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"
@@ -41,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
@@ -53,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
@@ -71,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,9 @@ 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
+
       # Creates a new Result.
       #
       # ==== Parameters
@@ -35,11 +38,13 @@ 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)
+      def initialize(text:, confidence:, processing_time_ms:, warnings: [], engine: nil)
         @text = text
         @confidence = confidence
         @processing_time_ms = processing_time_ms
         @warnings = warnings
+        @engine = engine
       end
 
       # Returns whether OCR successfully extracted text.
@@ -61,7 +66,8 @@ module ActiveStorage
           text: text,
           confidence: confidence,
           processing_time_ms: processing_time_ms,
-          warnings: warnings
+          warnings: warnings,
+          engine: engine
         }
       end
 
@@ -71,11 +77,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.1"
+    VERSION = "0.2.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
   #

data/lib/generators/activestorage_ocr/install/USAGE

@@ -0,0 +1,12 @@
+Description:
+    Installs the OCR server binary and creates a wrapper script.
+
+Example:
+    rails generate activestorage_ocr:install
+
+    This will create:
+        bin/activestorage-ocr-server - Wrapper script that runs the OCR server
+        bin/dist/activestorage-ocr-server - The actual binary (gitignored)
+
+    And update:
+        .gitignore - Adds /bin/dist/ to ignore the binary

data/lib/generators/activestorage_ocr/install/install_generator.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module ActivestorageOcr
+  module Generators
+    # Installs the OCR server binary and creates a binstub.
+    #
+    # This generator creates a bin/activestorage-ocr-server script that
+    # automatically downloads the binary if needed and runs it.
+    #
+    # == Usage
+    #
+    #   rails generate activestorage_ocr:install
+    #
+    # == What it does
+    #
+    # 1. Creates bin/activestorage-ocr-server (wrapper script)
+    # 2. Downloads binary to bin/dist/activestorage-ocr-server
+    # 3. Adds bin/dist/ to .gitignore
+    #
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Installs the OCR server binary and creates a binstub"
+
+      def create_binstub
+        template "bin/activestorage-ocr-server", "bin/activestorage-ocr-server"
+        chmod "bin/activestorage-ocr-server", 0o755
+      end
+
+      def update_gitignore
+        gitignore_path = Rails.root.join(".gitignore")
+        return unless File.exist?(gitignore_path)
+
+        gitignore_content = File.read(gitignore_path)
+        return if gitignore_content.include?("/bin/dist")
+
+        append_to_file ".gitignore", "\n# OCR server binary\n/bin/dist/\n"
+      end
+
+      def download_binary
+        say "Downloading OCR server binary...", :green
+        require "activestorage/ocr/binary"
+        dist_dir = Rails.root.join("bin", "dist")
+        ActiveStorage::Ocr::Binary.install!(path: dist_dir.to_s)
+      end
+
+      def show_instructions
+        say ""
+        say "OCR server installed successfully!", :green
+        say ""
+        say "Add to your Procfile:", :yellow
+        say "  ocr: bin/activestorage-ocr-server --host 127.0.0.1 --port 9292"
+        say ""
+        say "Configure the server URL in config/initializers/activestorage_ocr.rb:", :yellow
+        say "  ActiveStorage::Ocr.configure do |config|"
+        say "    config.server_url = ENV.fetch('ACTIVESTORAGE_OCR_SERVER_URL', 'http://127.0.0.1:9292')"
+        say "  end"
+        say ""
+      end
+    end
+  end
+end

data/lib/generators/activestorage_ocr/install/templates/bin/activestorage-ocr-server

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -e
+
+# Navigate to app root
+cd "$(dirname "$0")/.."
+
+BINARY_PATH="./bin/dist/activestorage-ocr-server"
+
+# Download binary if not present
+if [ ! -f "$BINARY_PATH" ]; then
+  echo "OCR server binary not found. Downloading..."
+  ./bin/rails activestorage_ocr:install path=./bin/dist
+fi
+
+# Execute the binary with all passed arguments
+exec "$BINARY_PATH" "$@"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activestorage-ocr
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors:
 - Michael Rispoli
@@ -112,6 +112,9 @@ files:
 - lib/activestorage/ocr/railtie.rb
 - lib/activestorage/ocr/result.rb
 - lib/activestorage/ocr/version.rb
+- lib/generators/activestorage_ocr/install/USAGE
+- lib/generators/activestorage_ocr/install/install_generator.rb
+- lib/generators/activestorage_ocr/install/templates/bin/activestorage-ocr-server
 homepage: https://github.com/Cause-of-a-Kind/activestorage-ocr
 licenses:
 - MIT