activestorage-ocr

OCR for Rails Active Storage attachments, powered by Rust and ocrs.

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.

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

Supported Formats:

• Images: PNG, JPEG, TIFF, WebP, GIF, BMP
• Documents: PDF (both embedded text and scanned/image PDFs)

Architecture: Separate process with HTTP/JSON communication (inspired by AnyCable)

• Rust server handles CPU-intensive OCR processing
• Ruby gem provides seamless Rails integration
• Simple HTTP/JSON protocol for easy debugging

• Ruby 3.2+
• Rails 7.0+ with Active Storage
• Rust (for building from source) or pre-built binaries from releases

Add to your Gemfile:

gem "activestorage-ocr"

Then install the OCR server binary:

bundle install
bin/rails activestorage_ocr:install

1. Start the OCR server:

   bin/rails activestorage_ocr:start

2. Use the client in your Rails app:

   # In rails console or your code
   client = ActiveStorage::Ocr::Client.new
   
   # Check server health
   client.healthy?  # => true
   
   # 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
   
   # Extract text from an Active Storage attachment
   result = client.extract_text(document.file)

# config/initializers/activestorage_ocr.rb
ActiveStorage::Ocr.configure do |config|
  config.server_host = "127.0.0.1"
  config.server_port = 9292
  config.timeout = 60
end

# Install the OCR server binary for your platform
bin/rails activestorage_ocr:install

# Start the OCR server
bin/rails activestorage_ocr:start

# Check server health
bin/rails activestorage_ocr:health

# Show binary info (platform, path, version)
bin/rails activestorage_ocr:info

The Rust server exposes these HTTP endpoints:

# Health check
curl http://localhost:9292/health

# OCR an image
curl -X POST http://localhost:9292/ocr \
  -F "file=@document.png;type=image/png"

# Build the Rust server
cd rust
cargo build --release

# The binary will be at rust/target/release/activestorage-ocr-server

# Ruby unit tests
bundle exec rake test

# Rust tests
cd rust && cargo test

# Integration tests (requires server running)
cd rust && ./target/release/activestorage-ocr-server &
cd test/sandbox && RAILS_ENV=test bin/rails test

# Format Rust code
cd rust && cargo fmt

# Check for Rust warnings
cd rust && cargo clippy

See CONTRIBUTING.md for development setup and guidelines.

MIT License - see LICENSE file.