Behaviour module for OCR backends in the Kreuzberg plugin system.

This module defines the interface that all OCR backend implementations must follow to integrate with the Kreuzberg document extraction library. OCR backends are responsible for extracting text from images using optical character recognition.

Overview

An OCR backend is a module that implements this behaviour and provides the ability to:

• Initialize and shutdown the OCR engine
• Detect supported languages
• Process image binary data and extract text
• Process image files and extract text
• Report version information

Implementing an OCR Backend

To create a custom OCR backend, create a module that implements this behaviour:

defmodule MyApp.CustomOcrBackend do
  @behaviour Kreuzberg.Plugin.OcrBackend

  @impl true
  def name(), do: "custom_ocr"

  @impl true
  def supported_languages(), do: ["eng", "deu", "fra"]

  @impl true
  def initialize() do
    # Initialize your OCR engine
    :ok
  end

  @impl true
  def shutdown() do
    # Clean up resources
    :ok
  end

  @impl true
  def process_image(image_data, language) when is_binary(image_data) do
    # Extract text from image binary data
    {:ok, extracted_text}
  end

  @impl true
  def process_file(path, language) when is_binary(path) do
    # Extract text from image file
    {:ok, extracted_text}
  end

  @impl true
  def version(), do: "1.0.0"
end

Language Codes

Language codes should follow the ISO 639-3 standard for consistency:

• "eng" - English
• "deu" - German
• "fra" - French
• "spa" - Spanish
• "ita" - Italian
• "jpn" - Japanese
• "rus" - Russian
• "chi" - Chinese (Simplified)
• "chi_tra" - Chinese (Traditional)

Error Handling

All functions that can fail should return {:error, reason} tuples where reason is a descriptive string. Use clear, actionable error messages to help users debug issues.

Common error scenarios:

• Invalid image format: {:error, "Unsupported image format: png"}
• Unsupported language: {:error, "Language not supported: xyz"}
• Engine initialization failure: {:error, "Failed to initialize OCR engine"}
• File read errors: {:error, "Cannot read file: /path/to/file"}
• OCR processing errors: {:error, "OCR processing failed: timeout"}

Example: Tesseract-based Backend

Here's a complete example of implementing a Tesseract-based OCR backend:

• name() - Returns "tesseract"
• supported_languages() - Returns list of supported language codes
• initialize() - Verifies tesseract is installed via System.cmd("tesseract", ["--version"])
• shutdown() - Performs cleanup (Tesseract requires no explicit shutdown)
• process_image(image_data, language) - Writes image to temp file, runs tesseract with language param, reads output text file, cleans up temp files
• process_file(path, language) - Reads image file and delegates to process_image/2
• version() - Runs tesseract --version and extracts the version string

Error handling covers:

• Missing tesseract installation
• File I/O errors during temporary file operations
• OCR processing failures

Integration with Kreuzberg

Once implemented, OCR backends can be integrated into the Kreuzberg extraction pipeline through the configuration system:

config = %Kreuzberg.ExtractionConfig{
  ocr: %{
    "enabled" => true,
    "backend" => "tesseract",
    "languages" => ["eng", "deu"]
  }
}

{:ok, result} = Kreuzberg.extract(pdf_binary, "application/pdf", config)

Callbacks