// Generated by alef. Do not edit by hand.
@file:Suppress(
    "ktlint:standard:trailing-comma-on-call-site",
    "ktlint:standard:trailing-comma-on-declaration-site",
    "ktlint:standard:spacing-between-declarations-with-comments",
    "ktlint:standard:spacing-between-declarations-with-annotations",
    "ktlint:standard:when-entry-bracing",
    "ktlint:standard:blank-line-between-when-conditions",
    "ktlint:standard:blank-line-before-declaration",
    "ktlint:standard:chain-method-continuation",
    "ktlint:standard:annotation",
    "ktlint:standard:max-line-length",
    "ktlint:standard:no-semi",
    "ktlint:standard:statement-wrapping",
    "MaxLineLength",
    "TooManyFunctions",
    "FunctionParameterNaming",
    "LongParameterList",
    "CyclomaticComplexMethod",
    "LongMethod",
)

package dev.kreuzberg

import java.nio.file.Path

/**
 * Trait for OCR backend plugins.
 *
 * Implement this trait to add custom OCR capabilities. OCR backends can be:
 *
 * - Native Rust implementations (like Tesseract)
 * - FFI bridges to Python libraries (like EasyOCR, PaddleOCR)
 * - Cloud-based OCR services (Google Vision, AWS Textract, etc.)
 *
 * # Thread Safety
 *
 * OCR backends must be thread-safe (`Send + Sync`) to support concurrent processing.
 */
interface IOcrBackend {
    fun name(): String
    fun version(): String
    fun initialize() {}
    fun shutdown() {}
    /**
     * Process an image and extract text via OCR.
     *
     * **Returns:**
     *
     * An `ExtractionResult` containing the extracted text and metadata.
     *
     * **Errors:**
     *
     * - `KreuzbergError.Ocr` - OCR processing failed
     * - `KreuzbergError.Validation` - Invalid image format or configuration
     * - `KreuzbergError.Io` - I/O errors (these always bubble up)
     *
     * # Reading `backend_options`
     *
     * Backends that support runtime tuning can read `config.backend_options` and
     * deserialize only the keys they care about. Unknown keys are silently ignored,
     * so multiple backends can coexist in a pipeline without key conflicts.
     */
    suspend fun processImage(imageBytes: ByteArray, config: OcrConfig): ExtractionResult
    /**
     * Process a file and extract text via OCR.
     *
     * Default implementation reads the file and calls `process_image`.
     * Override for custom file handling or optimizations.
     *
     * **Errors:**
     *
     * Same as `process_image`, plus file I/O errors.
     */
    suspend fun processImageFile(path: java.nio.file.Path, config: OcrConfig): ExtractionResult
    /**
     * Check if this backend supports a given language code.
     *
     * **Returns:**
     *
     * `true` if the language is supported, `false` otherwise.
     */
    fun supportsLanguage(lang: String): Boolean
    /**
     * Get the backend type identifier.
     *
     * **Returns:**
     *
     * The backend type enum value.
     */
    fun backendType(): OcrBackendType
    /**
     * Optional: Get a list of all supported languages.
     *
     * Defaults to empty list. Override to provide comprehensive language support info.
     */
    fun supportedLanguages(): List<String>
    /**
     * Optional: Check if the backend supports table detection.
     *
     * Defaults to `false`. Override if your backend can detect and extract tables.
     */
    fun supportsTableDetection(): Boolean
    /**
     * Check if the backend supports direct document-level processing (e.g. for PDFs).
     *
     * Defaults to `false`. Override if the backend has optimized document processing.
     */
    fun supportsDocumentProcessing(): Boolean
    /**
     * Process a document file directly via OCR.
     *
     * Only called if `supports_document_processing` returns `true`.
     */
    suspend fun processDocument(path: java.nio.file.Path, config: OcrConfig): ExtractionResult
}
