activestorage-ocr 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '06842e85669ce35ba5e03695a92bf5acaccf8519cbfa57d8f4803664757bcccd'
+  data.tar.gz: d513b79b0691862d8f79df97a4fd3da02a61c56b5eacc027723a9a5515218efc
+SHA512:
+  metadata.gz: 7bfd336fccd12c9dfa437671c0e318fedc5ead6bae106ddd91a85d05e72dc2d1efabc00d098614fce7a3791a12a94db6668110f65a32ea7894cf15646f668d7e
+  data.tar.gz: d32683900ac1e7136b5e8ef6b322acd75587dcd3c9a5aa62d08bddb5d45083137d42e19cdb02c6518c25f19cf9d704196c8dd86b0f8a2cbbd1fbd6f52c430bae

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,171 @@
+# activestorage-ocr
+
+[![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).
+
+## 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.
+
+**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
+
+## Requirements
+
+- Ruby 3.2+
+- Rails 7.0+ with Active Storage
+- Rust (for building from source) or pre-built binaries from releases
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "activestorage-ocr"
+```
+
+Then install the OCR server binary:
+
+```bash
+bundle install
+bundle exec rake activestorage_ocr:install
+```
+
+## Quick Start
+
+1. **Start the OCR server:**
+
+   ```bash
+   bundle exec rake activestorage_ocr:start
+   ```
+
+2. **Use the client in your Rails app:**
+
+   ```ruby
+   # 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)
+   ```
+
+## 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
+end
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ACTIVESTORAGE_OCR_HOST` | `127.0.0.1` | Server host |
+| `ACTIVESTORAGE_OCR_PORT` | `9292` | Server port |
+
+## Rake Tasks
+
+```bash
+# Install the OCR server binary for your platform
+bundle exec rake activestorage_ocr:install
+
+# Start the OCR server
+bundle exec rake activestorage_ocr:start
+
+# Check server health
+bundle exec rake activestorage_ocr:health
+
+# Show binary info (platform, path, version)
+bundle exec rake activestorage_ocr:info
+```
+
+## API Endpoints
+
+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 |
+
+### Example with curl
+
+```bash
+# Health check
+curl http://localhost:9292/health
+
+# OCR an image
+curl -X POST http://localhost:9292/ocr \
+  -F "file=@document.png;type=image/png"
+```
+
+## Development
+
+### Building from source
+
+```bash
+# Build the Rust server
+cd rust
+cargo build --release
+
+# The binary will be at rust/target/release/activestorage-ocr-server
+```
+
+### Running tests
+
+```bash
+# 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
+```
+
+### Code style
+
+```bash
+# Format Rust code
+cd rust && cargo fmt
+
+# Check for Rust warnings
+cd rust && cargo clippy
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file.

data/lib/activestorage/ocr/analyzer.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module Ocr
+    # Active Storage analyzer for OCR processing.
+    #
+    # This analyzer integrates with Active Storage's analysis system to
+    # automatically extract text from uploaded images and PDFs.
+    #
+    # When registered with Active Storage, it will automatically process
+    # supported file types and store OCR results in the blob's metadata.
+    #
+    # == Metadata
+    #
+    # After analysis, blobs will have the following metadata:
+    # * +ocr_text+ - The extracted text
+    # * +ocr_confidence+ - Confidence score (0.0 to 1.0)
+    # * +ocr_processed_at+ - ISO 8601 timestamp
+    #
+    # == Example
+    #
+    #   document.file.analyze
+    #   document.file.metadata["ocr_text"]  # => "Extracted text..."
+    #
+    class Analyzer < ActiveStorage::Analyzer
+      # Determines if this analyzer can process the blob.
+      #
+      # ==== Parameters
+      #
+      # * +blob+ - An ActiveStorage::Blob instance
+      #
+      # ==== Returns
+      #
+      # +true+ if the blob's content type is supported.
+      def self.accept?(blob)
+        ActiveStorage::Ocr.configuration.accept_content_type?(blob.content_type)
+      end
+
+      # Extracts OCR metadata from the blob.
+      #
+      # Called by Active Storage during analysis.
+      #
+      # ==== Returns
+      #
+      # A Hash containing OCR results, or an empty Hash if extraction fails.
+      def metadata
+        result = extract_text
+        return {} unless result&.success?
+
+        result.to_metadata
+      rescue Error => e
+        Rails.logger.error("[ActiveStorage::Ocr] OCR failed: #{e.message}") if defined?(Rails)
+        {}
+      end
+
+      private
+
+      # Performs the OCR extraction.
+      def extract_text
+        Client.new.extract_text(blob)
+      end
+    end
+  end
+end

data/lib/activestorage/ocr/binary.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "net/http"
+require "uri"
+require "rubygems/package"
+require "zlib"
+
+module ActiveStorage
+  module Ocr
+    # Manages the OCR server binary.
+    #
+    # Handles downloading pre-built binaries from GitHub releases and
+    # detecting the appropriate platform.
+    #
+    # == Supported Platforms
+    #
+    # * darwin-x86_64 (macOS Intel)
+    # * darwin-aarch64 (macOS Apple Silicon)
+    # * linux-x86_64 (Linux x86_64)
+    # * linux-aarch64 (Linux ARM64)
+    #
+    # == Usage
+    #
+    #   # Install the binary for the current platform
+    #   ActiveStorage::Ocr::Binary.install!
+    #
+    #   # Check if binary is installed
+    #   ActiveStorage::Ocr::Binary.installed?  # => true
+    #
+    #   # Get the path to the binary
+    #   ActiveStorage::Ocr::Binary.binary_path
+    #
+    class Binary
+      # GitHub repository for downloading releases.
+      GITHUB_REPO = "Cause-of-a-Kind/activestorage-ocr"
+
+      # Name of the server binary.
+      BINARY_NAME = "activestorage-ocr-server"
+
+      class << self
+        # Detects the current platform.
+        #
+        # ==== Returns
+        #
+        # A String like "darwin-x86_64" or "linux-aarch64".
+        #
+        # ==== Raises
+        #
+        # RuntimeError if the OS or architecture is unsupported.
+        def platform
+          os = case RbConfig::CONFIG["host_os"]
+               when /darwin/i then "darwin"
+               when /linux/i then "linux"
+               else
+                 raise "Unsupported OS: #{RbConfig::CONFIG['host_os']}"
+               end
+
+          arch = case RbConfig::CONFIG["host_cpu"]
+                 when /x86_64|amd64/i then "x86_64"
+                 when /arm64|aarch64/i then "aarch64"
+                 else
+                   raise "Unsupported architecture: #{RbConfig::CONFIG['host_cpu']}"
+                 end
+
+          "#{os}-#{arch}"
+        end
+
+        # Returns the path where the binary is installed.
+        #
+        # ==== Returns
+        #
+        # Absolute path to the binary.
+        def binary_path
+          @binary_path ||= File.join(install_dir, BINARY_NAME)
+        end
+
+        # Returns the installation directory.
+        #
+        # Creates the directory if it doesn't exist.
+        def install_dir
+          @install_dir ||= begin
+            dir = File.join(gem_root, "bin")
+            FileUtils.mkdir_p(dir)
+            dir
+          end
+        end
+
+        # Returns the gem's root directory.
+        def gem_root
+          @gem_root ||= File.expand_path("../../../..", __FILE__)
+        end
+
+        # Checks if the binary is installed and executable.
+        #
+        # ==== Returns
+        #
+        # +true+ if the binary exists and is executable.
+        def installed?
+          File.executable?(binary_path)
+        end
+
+        # Returns the gem version.
+        #
+        # Used to determine which release to download.
+        def version
+          ActiveStorage::Ocr::VERSION
+        end
+
+        # Returns the download URL for the current platform.
+        #
+        # ==== Returns
+        #
+        # GitHub releases URL for the platform-specific tarball.
+        def download_url
+          tag = "v#{version}"
+          filename = "activestorage-ocr-server-#{platform}.tar.gz"
+          "https://github.com/#{GITHUB_REPO}/releases/download/#{tag}/#{filename}"
+        end
+
+        # Downloads and installs the binary.
+        #
+        # Downloads from GitHub releases and extracts to the gem's bin directory.
+        #
+        # ==== Parameters
+        #
+        # * +force+ - If true, reinstalls even if already installed
+        #
+        # ==== Returns
+        #
+        # Path to the installed binary.
+        #
+        # ==== Raises
+        #
+        # RuntimeError if the download fails.
+        def install!(force: false)
+          return binary_path if installed? && !force
+
+          puts "Downloading activestorage-ocr-server for #{platform}..."
+
+          uri = URI(download_url)
+          response = fetch_with_redirects(uri)
+
+          unless response.is_a?(Net::HTTPSuccess)
+            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"
+          end
+
+          extract_binary(response.body)
+          puts "Installed to #{binary_path}"
+          binary_path
+        end
+
+        private
+
+        # Fetches a URL, following redirects.
+        def fetch_with_redirects(uri, limit = 10)
+          raise "Too many redirects" if limit == 0
+
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = uri.scheme == "https"
+
+          request = Net::HTTP::Get.new(uri)
+          response = http.request(request)
+
+          case response
+          when Net::HTTPRedirection
+            location = URI(response["location"])
+            fetch_with_redirects(location, limit - 1)
+          else
+            response
+          end
+        end
+
+        # Extracts the binary from a gzipped tarball.
+        def extract_binary(tarball_data)
+          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|
+              f.write(entry.read)
+            end
+            File.chmod(0o755, binary_path)
+            return
+          end
+
+          raise "Binary not found in tarball"
+        ensure
+          gz&.close
+        end
+      end
+    end
+  end
+end

data/lib/activestorage/ocr/client.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module Ocr
+    # HTTP client for communicating with the OCR server.
+    #
+    # The Client handles all communication with the Rust OCR server,
+    # including file uploads and response parsing.
+    #
+    # == Basic Usage
+    #
+    #   client = ActiveStorage::Ocr::Client.new
+    #
+    #   # Extract text from an Active Storage blob
+    #   result = client.extract_text(document.file)
+    #
+    #   # Extract text from a file path
+    #   result = client.extract_text_from_path("/path/to/image.png")
+    #
+    #   # Check server health
+    #   client.healthy?  # => true
+    #
+    class Client
+      # Creates a new Client.
+      #
+      # ==== Parameters
+      #
+      # * +config+ - Configuration object (defaults to global configuration)
+      def initialize(config: ActiveStorage::Ocr.configuration)
+        @config = config
+      end
+
+      # Extracts text from an Active Storage blob.
+      #
+      # Opens the blob temporarily and sends it to the OCR server.
+      #
+      # ==== Parameters
+      #
+      # * +blob+ - An ActiveStorage::Blob instance
+      #
+      # ==== Returns
+      #
+      # A Result object with extracted text and metadata.
+      #
+      # ==== Raises
+      #
+      # * ConnectionError - if the server is unreachable
+      # * ServerError - if the server returns an error
+      def extract_text(blob)
+        blob.open do |file|
+          extract_text_from_file(file, blob.content_type, blob.filename.to_s)
+        end
+      end
+
+      # Extracts text from 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 Result object with extracted text and metadata.
+      #
+      # ==== Raises
+      #
+      # * ConnectionError - if the server is unreachable
+      # * ServerError - if the server returns an error
+      def extract_text_from_path(path, content_type: nil, filename: 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)
+        end
+      end
+
+      # Extracts text from an IO object.
+      #
+      # This is the low-level method that performs the actual HTTP request.
+      #
+      # ==== Parameters
+      #
+      # * +file+ - An IO object (File, StringIO, etc.)
+      # * +content_type+ - MIME type of the file
+      # * +filename+ - Filename to send to the server
+      #
+      # ==== Returns
+      #
+      # A Result object with extracted text and metadata.
+      #
+      # ==== Raises
+      #
+      # * 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|
+          req.body = {
+            file: Faraday::Multipart::FilePart.new(
+              file,
+              content_type,
+              filename
+            )
+          }
+        end
+
+        handle_response(response)
+      rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
+        raise ConnectionError, "Failed to connect to OCR server: #{e.message}"
+      end
+
+      # Checks if the OCR server is healthy.
+      #
+      # ==== Returns
+      #
+      # +true+ if the server responds with status "ok", +false+ otherwise.
+      def healthy?
+        response = connection.get("/health")
+        response.success? && JSON.parse(response.body)["status"] == "ok"
+      rescue StandardError
+        false
+      end
+
+      # Gets information about the OCR server.
+      #
+      # ==== Returns
+      #
+      # A Hash with server information including:
+      # * +:version+ - Server version
+      # * +:supported_formats+ - Array of supported MIME types
+      #
+      # ==== Raises
+      #
+      # * ConnectionError - if the server is unreachable
+      def server_info
+        response = connection.get("/info")
+        JSON.parse(response.body, symbolize_names: true)
+      rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
+        raise ConnectionError, "Failed to connect to OCR server: #{e.message}"
+      end
+
+      private
+
+      # Returns the Faraday connection, creating it if necessary.
+      def connection
+        @connection ||= Faraday.new(url: @config.server_url) do |f|
+          f.request :multipart
+          f.options.timeout = @config.timeout
+          f.options.open_timeout = @config.open_timeout
+          f.adapter Faraday.default_adapter
+        end
+      end
+
+      # Parses the server response and returns a Result.
+      def handle_response(response)
+        unless response.success?
+          error_body = JSON.parse(response.body) rescue {}
+          raise ServerError, error_body["error"] || "OCR server returned #{response.status}"
+        end
+
+        data = JSON.parse(response.body, symbolize_names: true)
+
+        Result.new(
+          text: data[:text],
+          confidence: data[:confidence],
+          processing_time_ms: data[:processing_time_ms],
+          warnings: data[:warnings] || []
+        )
+      end
+    end
+  end
+end

data/lib/activestorage/ocr/configuration.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module Ocr
+    # Configuration options for the OCR module.
+    #
+    # Settings can be configured via environment variables or the configure block:
+    #
+    #   ActiveStorage::Ocr.configure do |config|
+    #     config.server_url = "http://localhost:9292"
+    #     config.timeout = 60
+    #   end
+    #
+    # == Environment Variables
+    #
+    # * +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)
+    #
+    class Configuration
+      # The URL of the OCR server.
+      attr_accessor :server_url
+
+      # Request timeout in seconds.
+      attr_accessor :timeout
+
+      # Connection open timeout in seconds.
+      attr_accessor :open_timeout
+
+      # Array of MIME types that the analyzer will process.
+      attr_accessor :content_types
+
+      # Creates a new Configuration with default values.
+      #
+      # Defaults are read from environment variables if set.
+      def initialize
+        @server_url = ENV.fetch("ACTIVESTORAGE_OCR_SERVER_URL", "http://localhost:9292")
+        @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
+      end
+
+      # Returns the default list of supported content types.
+      #
+      # Includes common image formats and PDF.
+      def default_content_types
+        %w[
+          image/png
+          image/jpeg
+          image/gif
+          image/bmp
+          image/webp
+          image/tiff
+          application/pdf
+        ]
+      end
+
+      # Checks if the given content type is supported.
+      #
+      # ==== Parameters
+      #
+      # * +content_type+ - A MIME type string (e.g., "image/png")
+      #
+      # ==== Returns
+      #
+      # +true+ if the content type is in the supported list, +false+ otherwise.
+      def accept_content_type?(content_type)
+        content_types.include?(content_type)
+      end
+    end
+  end
+end

data/lib/activestorage/ocr/railtie.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module Ocr
+    # Rails integration via Railtie.
+    #
+    # Automatically registers the OCR analyzer with Active Storage and
+    # provides rake tasks for managing the OCR server.
+    #
+    # == Rake Tasks
+    #
+    # * +activestorage_ocr:install+ - Download and install the server binary
+    # * +activestorage_ocr:start+ - Start the OCR server
+    # * +activestorage_ocr:health+ - Check if the server is responding
+    # * +activestorage_ocr:info+ - Show binary and platform information
+    #
+    class Railtie < Rails::Railtie
+      # Registers the OCR analyzer with Active Storage.
+      initializer "activestorage-ocr.add_analyzer" do
+        config.after_initialize do
+          # Prepend our analyzer so it runs before other analyzers
+          if defined?(ActiveStorage) && ActiveStorage.respond_to?(:analyzers)
+            ActiveStorage.analyzers.prepend(ActiveStorage::Ocr::Analyzer)
+          end
+        end
+      end
+
+      # Defines rake tasks for server management.
+      rake_tasks do
+        namespace :activestorage_ocr do
+          desc "Install the OCR server binary"
+          task :install do
+            ActiveStorage::Ocr::Binary.install!
+          end
+
+          desc "Check OCR server health"
+          task health: :environment do
+            client = ActiveStorage::Ocr::Client.new
+            if client.healthy?
+              puts "OCR server is healthy"
+              info = client.server_info
+              puts "  Version: #{info[:version]}"
+              puts "  Supported formats: #{info[:supported_formats].join(', ')}"
+            else
+              puts "OCR server is not responding"
+              exit 1
+            end
+          end
+
+          desc "Start the OCR server"
+          task :start do
+            binary = ActiveStorage::Ocr::Binary.binary_path
+            unless File.executable?(binary)
+              puts "Binary not found. Installing..."
+              ActiveStorage::Ocr::Binary.install!
+            end
+
+            config = ActiveStorage::Ocr.configuration
+            host = config.server_host.gsub(%r{https?://}, "")
+            port = config.server_port
+
+            puts "Starting OCR server on #{host}:#{port}..."
+            exec(binary, "--host", host, "--port", port.to_s)
+          end
+
+          desc "Show binary info"
+          task :info do
+            puts "Platform: #{ActiveStorage::Ocr::Binary.platform}"
+            puts "Binary path: #{ActiveStorage::Ocr::Binary.binary_path}"
+            puts "Installed: #{ActiveStorage::Ocr::Binary.installed?}"
+            puts "Version: #{ActiveStorage::Ocr::Binary.version}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/activestorage/ocr/result.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module Ocr
+    # Represents the result of an OCR operation.
+    #
+    # Contains the extracted text, confidence score, and processing metadata.
+    #
+    # == Example
+    #
+    #   result = client.extract_text(blob)
+    #   if result.success?
+    #     puts result.text
+    #     puts "Confidence: #{result.confidence}"
+    #   end
+    #
+    class Result
+      # The extracted text content.
+      attr_reader :text
+
+      # Confidence score from 0.0 to 1.0.
+      attr_reader :confidence
+
+      # Time taken to process the file in milliseconds.
+      attr_reader :processing_time_ms
+
+      # Array of warning messages from the OCR server.
+      attr_reader :warnings
+
+      # Creates a new Result.
+      #
+      # ==== Parameters
+      #
+      # * +text+ - The extracted text
+      # * +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: [])
+        @text = text
+        @confidence = confidence
+        @processing_time_ms = processing_time_ms
+        @warnings = warnings
+      end
+
+      # Returns whether OCR successfully extracted text.
+      #
+      # ==== Returns
+      #
+      # +true+ if text was extracted, +false+ if text is nil or empty.
+      def success?
+        !text.nil? && !text.empty?
+      end
+
+      # Converts the result to a Hash.
+      #
+      # ==== Returns
+      #
+      # A Hash with all result attributes.
+      def to_h
+        {
+          text: text,
+          confidence: confidence,
+          processing_time_ms: processing_time_ms,
+          warnings: warnings
+        }
+      end
+
+      # Converts the result to Active Storage metadata format.
+      #
+      # This format is suitable for storing in blob metadata.
+      #
+      # ==== Returns
+      #
+      # A Hash with +:ocr_text+, +:ocr_confidence+, and +:ocr_processed_at+.
+      def to_metadata
+        {
+          ocr_text: text,
+          ocr_confidence: confidence,
+          ocr_processed_at: Time.now.utc.iso8601
+        }
+      end
+    end
+  end
+end

data/lib/activestorage/ocr/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ActiveStorage
+  module Ocr
+    VERSION = "0.1.0"
+  end
+end

data/lib/activestorage/ocr.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/multipart"
+require "json"
+
+require_relative "ocr/version"
+require_relative "ocr/configuration"
+require_relative "ocr/client"
+require_relative "ocr/result"
+require_relative "ocr/binary"
+
+if defined?(Rails)
+  require_relative "ocr/analyzer"
+  require_relative "ocr/railtie"
+end
+
+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.
+  #
+  # == Configuration
+  #
+  #   ActiveStorage::Ocr.configure do |config|
+  #     config.server_url = "http://localhost:9292"
+  #     config.timeout = 30
+  #   end
+  #
+  # == Basic Usage
+  #
+  #   # Extract text from an Active Storage blob
+  #   result = ActiveStorage::Ocr.extract_text(document.file)
+  #   result.text        # => "Extracted text..."
+  #   result.confidence  # => 0.95
+  #
+  # == Error Handling
+  #
+  # All errors inherit from ActiveStorage::Ocr::Error:
+  # - ActiveStorage::Ocr::ConnectionError - server unreachable
+  # - ActiveStorage::Ocr::ServerError - server returned an error
+  #
+  module Ocr
+    # Base error class for all OCR errors.
+    class Error < StandardError; end
+
+    # Raised when the OCR server returns an error response.
+    class ServerError < Error; end
+
+    # Raised when the OCR server is unreachable or times out.
+    class ConnectionError < Error; end
+
+    class << self
+      attr_writer :configuration
+
+      # Returns the current configuration.
+      #
+      # Creates a new Configuration with defaults if none exists.
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      # Configures the OCR module.
+      #
+      # ==== Example
+      #
+      #   ActiveStorage::Ocr.configure do |config|
+      #     config.server_url = "http://localhost:9292"
+      #     config.timeout = 60
+      #   end
+      def configure
+        yield(configuration)
+      end
+
+      # Resets configuration to defaults.
+      #
+      # Useful for testing.
+      def reset_configuration!
+        @configuration = Configuration.new
+      end
+
+      # Extracts text from an Active Storage blob.
+      #
+      # This is a convenience method that creates a new Client and calls
+      # extract_text on it.
+      #
+      # ==== Parameters
+      #
+      # * +blob+ - An ActiveStorage::Blob instance
+      #
+      # ==== Returns
+      #
+      # A Result object containing extracted text and metadata.
+      #
+      # ==== Raises
+      #
+      # * ConnectionError - if the server is unreachable
+      # * ServerError - if the server returns an error
+      def extract_text(blob)
+        Client.new.extract_text(blob)
+      end
+    end
+  end
+end

data/lib/activestorage-ocr.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "activestorage/ocr"

metadata

@@ -0,0 +1,139 @@
+--- !ruby/object:Gem::Specification
+name: activestorage-ocr
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Michael Rispoli
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activestorage
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-multipart
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Extract text from images and PDFs stored in Active Storage using a high-performance
+  Rust OCR server
+email:
+- mike.rispoli@causeofakind.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/activestorage-ocr.rb
+- lib/activestorage/ocr.rb
+- lib/activestorage/ocr/analyzer.rb
+- lib/activestorage/ocr/binary.rb
+- lib/activestorage/ocr/client.rb
+- lib/activestorage/ocr/configuration.rb
+- lib/activestorage/ocr/railtie.rb
+- lib/activestorage/ocr/result.rb
+- lib/activestorage/ocr/version.rb
+homepage: https://github.com/Cause-of-a-Kind/activestorage-ocr
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Cause-of-a-Kind/activestorage-ocr
+  source_code_uri: https://github.com/Cause-of-a-Kind/activestorage-ocr
+  changelog_uri: https://github.com/Cause-of-a-Kind/activestorage-ocr/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: OCR support for Rails Active Storage
+test_files: []