// Generated by alef. Do not edit by hand.

import 'kreuzberg_bridge_generated/lib.dart';
import 'dart:typed_data';

/// Abstract class for the `OcrBackend` Rust trait.
///
/// Implement this class and register your implementation via:
/// ```dart
/// class MyOcrBackend implements OcrBackend {
///   @override
///   Future<ExtractionResult> processImage(...) async { ... }
///   @override
///   Future<ExtractionResult> processImageFile(...) async { ... }
///   @override
///   Future<bool> supportsLanguage(...) async { ... }
///   @override
///   Future<OcrBackendType> backendType(...) async { ... }
///   @override
///   Future<List<String>> supportedLanguages(...) async { ... }
///   @override
///   Future<bool> supportsTableDetection(...) async { ... }
///   @override
///   Future<bool> supportsDocumentProcessing(...) async { ... }
///   @override
///   Future<ExtractionResult> processDocument(...) async { ... }
/// }
///
/// final impl = createOcrBackendDartImpl(
///   processImage: (...) => myInstance.processImage(...),
///   processImageFile: (...) => myInstance.processImageFile(...),
///   supportsLanguage: (...) => myInstance.supportsLanguage(...),
///   backendType: (...) => myInstance.backendType(...),
///   supportedLanguages: (...) => myInstance.supportedLanguages(...),
///   supportsTableDetection: (...) => myInstance.supportsTableDetection(...),
///   supportsDocumentProcessing: (...) => myInstance.supportsDocumentProcessing(...),
///   processDocument: (...) => myInstance.processDocument(...),
/// );
/// ```
///
abstract class OcrBackend {
  /// Process an image and extract text via OCR.
  ///
  /// # Arguments
  ///
  /// * `image_bytes` - Raw image data (JPEG, PNG, TIFF, etc.)
  /// * `config` - OCR configuration (language, PSM mode, etc.)
  ///
  /// # 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.
  ///
  /// ```rust
  /// async fn process_image(&self, image_bytes: &[u8], config: &OcrConfig) -> Result<ExtractionResult> {
  ///     // Read backend-specific options; unknown keys are silently ignored.
  ///     let fast_mode = config.backend_options
  ///         .as_ref()
  ///         .and_then(|v| v.get("mode"))
  ///         .and_then(|v| v.as_str())
  ///         .map(|s| s == "fast")
  ///         .unwrap_or(false);
  ///
  ///     if image_bytes.is_empty() {
  ///         return Err(kreuzberg::KreuzbergError::Validation {
  ///             message: "Empty image data".to_string(),
  ///             source: None,
  ///         });
  ///     }
  ///
  ///     let text = if fast_mode {
  ///         "Fast OCR result".to_string()
  ///     } else {
  ///         format!("Extracted text in language: {}", config.language)
  ///     };
  ///
  ///     Ok(ExtractionResult {
  ///         content: text,
  ///         mime_type: Cow::Borrowed("text/plain"),
  ///         ..Default::default()
  ///     })
  /// }
  /// ```
  /// throws anyhow::Error on failure
  Future<ExtractionResult> processImage(Uint8List imageBytes, OcrConfig config);
  /// Process a file and extract text via OCR.
  ///
  /// Default implementation reads the file and calls `process_image`.
  /// Override for custom file handling or optimizations.
  ///
  /// # Arguments
  ///
  /// * `path` - Path to the image file
  /// * `config` - OCR configuration
  ///
  /// # Errors
  ///
  /// Same as `process_image`, plus file I/O errors.
  /// throws anyhow::Error on failure
  Future<ExtractionResult> processImageFile(String path, OcrConfig config);
  /// Check if this backend supports a given language code.
  ///
  /// # Arguments
  ///
  /// * `lang` - ISO 639-2/3 language code (e.g., "eng", "deu", "fra")
  ///
  /// # Returns
  ///
  /// `true` if the language is supported, `false` otherwise.
  ///
  /// # Example
  ///
  /// ```rust
  /// fn supports_language(&self, lang: &str) -> bool {
  ///     self.languages.contains(&lang.to_string())
  /// }
  /// ```
  Future<bool> supportsLanguage(String lang);
  /// Get the backend type identifier.
  ///
  /// # Returns
  ///
  /// The backend type enum value.
  ///
  /// # Example
  ///
  /// ```rust
  /// fn backend_type(&self) -> OcrBackendType {
  ///     OcrBackendType::Tesseract
  /// }
  /// ```
  Future<OcrBackendType> backendType();
  /// Optional: Get a list of all supported languages.
  ///
  /// Defaults to empty list. Override to provide comprehensive language support info.
  Future<List<String>> supportedLanguages();
  /// Optional: Check if the backend supports table detection.
  ///
  /// Defaults to `false`. Override if your backend can detect and extract tables.
  Future<bool> supportsTableDetection();
  /// Check if the backend supports direct document-level processing (e.g. for PDFs).
  ///
  /// Defaults to `false`. Override if the backend has optimized document processing.
  Future<bool> supportsDocumentProcessing();
  /// Process a document file directly via OCR.
  ///
  /// Only called if `supports_document_processing` returns `true`.
  ///
  /// # Arguments
  ///
  /// * `path` - Path to the document file (e.g. .pdf)
  /// * `config` - OCR configuration
  /// throws anyhow::Error on failure
  Future<ExtractionResult> processDocument(String path, OcrConfig config);
}

/// Abstract class for the `PostProcessor` Rust trait.
///
/// Implement this class and register your implementation via:
/// ```dart
/// class MyPostProcessor implements PostProcessor {
///   @override
///   Future<void> process(...) async { ... }
///   @override
///   Future<ProcessingStage> processingStage(...) async { ... }
///   @override
///   Future<bool> shouldProcess(...) async { ... }
///   @override
///   Future<int> estimatedDurationMs(...) async { ... }
///   @override
///   Future<int> priority(...) async { ... }
/// }
///
/// final impl = createPostProcessorDartImpl(
///   process: (...) => myInstance.process(...),
///   processingStage: (...) => myInstance.processingStage(...),
///   shouldProcess: (...) => myInstance.shouldProcess(...),
///   estimatedDurationMs: (...) => myInstance.estimatedDurationMs(...),
///   priority: (...) => myInstance.priority(...),
/// );
/// ```
///
abstract class PostProcessor {
  /// Process an extraction result.
  ///
  /// Transform or enrich the extraction result. Can modify:
  /// - `content` - The extracted text
  /// - `metadata` - Add or update metadata fields
  /// - `tables` - Modify or enhance table data
  ///
  /// # Arguments
  ///
  /// * `result` - Mutable reference to the extraction result to process
  /// * `config` - Extraction configuration
  ///
  /// # Returns
  ///
  /// `Ok(())` if processing succeeded, `Err(...)` for fatal failures.
  ///
  /// # Errors
  ///
  /// Return errors for fatal processing failures. Non-fatal errors should be
  /// captured in metadata directly on the result.
  ///
  /// # Performance
  ///
  /// This signature avoids unnecessary cloning of large extraction results by
  /// taking a mutable reference instead of ownership. Processors modify the
  /// result in place.
  ///
  /// # Example - Language Detection
  ///
  /// ```rust
  /// async fn process(&self, result: &mut ExtractionResult, config: &ExtractionConfig)
  ///     -> Result<()> {
  ///     // Detect language (simplified - use real detection library in practice)
  ///     let language = "en"; // Placeholder detection
  ///
  ///     // Add to metadata
  ///     result.metadata.additional.insert("detected_language".to_string().into(), serde_json::json!(language));
  ///
  ///     Ok(())
  /// }
  /// ```
  ///
  /// # Example - Text Cleaning
  ///
  /// ```rust
  /// async fn process(&self, result: &mut ExtractionResult, config: &ExtractionConfig)
  ///     -> Result<()> {
  ///     // Remove excessive whitespace
  ///     result.content = result
  ///         .content
  ///         .split_whitespace()
  ///         .collect::<Vec<_>>()
  ///         .join(" ");
  ///
  ///     Ok(())
  /// }
  /// ```
  /// throws anyhow::Error on failure
  Future<void> process(ExtractionResult result, ExtractionConfig config);
  /// Get the processing stage for this post-processor.
  ///
  /// Determines when this processor runs in the pipeline.
  ///
  /// # Returns
  ///
  /// The `ProcessingStage` (Early, Middle, or Late).
  ///
  /// # Example
  ///
  /// ```rust
  /// fn processing_stage(&self) -> ProcessingStage {
  ///     ProcessingStage::Early  // Run before other processors
  /// }
  /// ```
  Future<ProcessingStage> processingStage();
  /// Optional: Check if this processor should run for a given result.
  ///
  /// Allows conditional processing based on MIME type, metadata, or content.
  /// Defaults to `true` (always run).
  ///
  /// # Arguments
  ///
  /// * `result` - The extraction result to check
  /// * `config` - Extraction configuration
  ///
  /// # Returns
  ///
  /// `true` if the processor should run, `false` to skip.
  ///
  /// # Example
  ///
  /// ```rust
  /// /// Only process PDF documents
  /// fn should_process(&self, result: &ExtractionResult, config: &ExtractionConfig) -> bool {
  ///     result.mime_type == "application/pdf"
  /// }
  /// ```
  Future<bool> shouldProcess(ExtractionResult result, ExtractionConfig config);
  /// Optional: Estimate processing time in milliseconds.
  ///
  /// Used for logging and debugging. Defaults to 0 (unknown).
  ///
  /// # Arguments
  ///
  /// * `result` - The extraction result to estimate for
  ///
  /// # Returns
  ///
  /// Estimated processing time in milliseconds.
  Future<int> estimatedDurationMs(ExtractionResult result);
  /// Execution priority within the processing stage.
  ///
  /// Higher values run first within the same `ProcessingStage`. Defaults to 50.
  /// Use 0-49 for fallback processors, 50 for normal processors, and 51-255
  /// for high-priority processors that should run early in their stage.
  Future<int> priority();
}

/// Abstract class for the `Validator` Rust trait.
///
/// Implement this class and register your implementation via:
/// ```dart
/// class MyValidator implements Validator {
///   @override
///   Future<void> validate(...) async { ... }
///   @override
///   Future<bool> shouldValidate(...) async { ... }
///   @override
///   Future<int> priority(...) async { ... }
/// }
///
/// final impl = createValidatorDartImpl(
///   validate: (...) => myInstance.validate(...),
///   shouldValidate: (...) => myInstance.shouldValidate(...),
///   priority: (...) => myInstance.priority(...),
/// );
/// ```
///
abstract class Validator {
  /// Validate an extraction result.
  ///
  /// Check the extraction result and return `Ok(())` if valid, or an error
  /// if validation fails.
  ///
  /// # Arguments
  ///
  /// * `result` - The extraction result to validate
  /// * `config` - Extraction configuration
  ///
  /// # Returns
  ///
  /// - `Ok(())` if validation passes
  /// - `Err(...)` if validation fails (extraction will fail)
  ///
  /// # Errors
  ///
  /// - `KreuzbergError::Validation` - Validation failed
  /// - Any other error type appropriate for the failure
  ///
  /// # Example - Content Length Validation
  ///
  /// ```rust
  /// async fn validate(&self, result: &ExtractionResult, config: &ExtractionConfig)
  ///     -> Result<()> {
  ///     let length = result.content.len();
  ///
  ///     if length < self.min {
  ///         return Err(KreuzbergError::validation(format!(
  ///             "Content too short: {} < {} characters",
  ///             length, self.min
  ///         )));
  ///     }
  ///
  ///     if length > self.max {
  ///         return Err(KreuzbergError::validation(format!(
  ///             "Content too long: {} > {} characters",
  ///             length, self.max
  ///         )));
  ///     }
  ///
  ///     Ok(())
  /// }
  /// ```
  ///
  /// # Example - Quality Score Validation
  ///
  /// ```rust
  /// async fn validate(&self, result: &ExtractionResult, config: &ExtractionConfig)
  ///     -> Result<()> {
  ///     // Check if quality_score exists in metadata
  ///     let score = result.metadata
  ///         .additional
  ///         .get("quality_score")
  ///         .and_then(|v| v.as_f64())
  ///         .unwrap_or(0.0);
  ///
  ///     if score < self.min_score {
  ///         return Err(KreuzbergError::validation(format!(
  ///             "Quality score too low: {} < {}",
  ///             score, self.min_score
  ///         )));
  ///     }
  ///
  ///     Ok(())
  /// }
  /// ```
  ///
  /// # Example - Security Validation
  ///
  /// ```rust
  /// async fn validate(&self, result: &ExtractionResult, config: &ExtractionConfig)
  ///     -> Result<()> {
  ///     // Check for blocked patterns
  ///     for pattern in &self.blocked_patterns {
  ///         if result.content.contains(pattern) {
  ///             return Err(KreuzbergError::validation(format!(
  ///                 "Content contains blocked pattern: {}",
  ///                 pattern
  ///             )));
  ///         }
  ///     }
  ///
  ///     Ok(())
  /// }
  /// ```
  /// throws anyhow::Error on failure
  Future<void> validate(ExtractionResult result, ExtractionConfig config);
  /// Optional: Check if this validator should run for a given result.
  ///
  /// Allows conditional validation based on MIME type, metadata, or content.
  /// Defaults to `true` (always run).
  ///
  /// # Arguments
  ///
  /// * `result` - The extraction result to check
  /// * `config` - Extraction configuration
  ///
  /// # Returns
  ///
  /// `true` if the validator should run, `false` to skip.
  ///
  /// # Example
  ///
  /// ```rust
  /// /// Only validate PDF documents
  /// fn should_validate(&self, result: &ExtractionResult, config: &ExtractionConfig) -> bool {
  ///     result.mime_type == "application/pdf"
  /// }
  /// ```
  Future<bool> shouldValidate(ExtractionResult result, ExtractionConfig config);
  /// Optional: Get the validation priority.
  ///
  /// Higher priority validators run first. Useful for ordering validation checks
  /// (e.g., run cheap validations before expensive ones).
  ///
  /// Default priority is 50.
  ///
  /// # Returns
  ///
  /// Priority value (higher = runs earlier).
  ///
  /// # Example
  ///
  /// ```rust
  /// /// Run this validator first (it's fast)
  /// fn priority(&self) -> i32 {
  ///     100
  /// }
  /// ```
  Future<int> priority();
}

/// Abstract class for the `EmbeddingBackend` Rust trait.
///
/// Implement this class and register your implementation via:
/// ```dart
/// class MyEmbeddingBackend implements EmbeddingBackend {
///   @override
///   Future<int> dimensions(...) async { ... }
///   @override
///   Future<List<Float64List>> embed(...) async { ... }
/// }
///
/// final impl = createEmbeddingBackendDartImpl(
///   dimensions: (...) => myInstance.dimensions(...),
///   embed: (...) => myInstance.embed(...),
/// );
/// ```
///
abstract class EmbeddingBackend {
  /// Embedding vector dimension. Must be `> 0` and must match the length of
  /// every vector returned by `embed`.
  Future<int> dimensions();
  /// Embed a batch of texts, returning one vector per input in order.
  ///
  /// # Errors
  ///
  /// Implementations should return `Plugin` for
  /// backend-specific failures. The dispatcher layers its own validation
  /// (length, per-vector dimension) on top.
  /// throws anyhow::Error on failure
  Future<List<Float64List>> embed(List<String> texts);
}

/// Abstract class for the `DocumentExtractor` Rust trait.
///
/// Implement this class and register your implementation via:
/// ```dart
/// class MyDocumentExtractor implements DocumentExtractor {
///   @override
///   Future<InternalDocumentBridge> extractBytes(...) async { ... }
///   @override
///   Future<InternalDocumentBridge> extractFile(...) async { ... }
///   @override
///   Future<List<String>> supportedMimeTypes(...) async { ... }
///   @override
///   Future<int> priority(...) async { ... }
///   @override
///   Future<bool> canHandle(...) async { ... }
/// }
///
/// final impl = createDocumentExtractorDartImpl(
///   extractBytes: (...) => myInstance.extractBytes(...),
///   extractFile: (...) => myInstance.extractFile(...),
///   supportedMimeTypes: (...) => myInstance.supportedMimeTypes(...),
///   priority: (...) => myInstance.priority(...),
///   canHandle: (...) => myInstance.canHandle(...),
/// );
/// ```
///
abstract class DocumentExtractor {
  /// Extract content from a byte array.
  ///
  /// This is the core extraction method that processes in-memory document data.
  ///
  /// # Arguments
  ///
  /// * `content` - Raw document bytes
  /// * `mime_type` - MIME type of the document (already validated)
  /// * `config` - Extraction configuration
  ///
  /// # Returns
  ///
  /// An `InternalDocument` containing the extracted elements, metadata, and tables.
  /// The pipeline will convert this into the public `ExtractionResult`.
  ///
  /// # Errors
  ///
  /// - `KreuzbergError::Parsing` - Document parsing failed
  /// - `KreuzbergError::Validation` - Invalid document structure
  /// - `KreuzbergError::Io` - I/O errors (these always bubble up)
  /// - `KreuzbergError::MissingDependency` - Required dependency not available
  /// throws anyhow::Error on failure
  Future<InternalDocumentBridge> extractBytes(Uint8List content, String mimeType, ExtractionConfig config);
  /// Extract content from a file.
  ///
  /// Default implementation reads the file and calls `extract_bytes`.
  /// Override for custom file handling, streaming, or memory optimizations.
  ///
  /// # Arguments
  ///
  /// * `path` - Path to the document file
  /// * `mime_type` - MIME type of the document (already validated)
  /// * `config` - Extraction configuration
  ///
  /// # Returns
  ///
  /// An `InternalDocument` containing the extracted elements, metadata, and tables.
  ///
  /// # Errors
  ///
  /// Same as `extract_bytes`, plus file I/O errors.
  /// throws anyhow::Error on failure
  Future<InternalDocumentBridge> extractFile(String path, String mimeType, ExtractionConfig config);
  /// Get the list of MIME types supported by this extractor.
  ///
  /// Can include exact MIME types and prefix patterns:
  /// - Exact: `"application/pdf"`, `"text/plain"`
  /// - Prefix: `"image/*"` (matches any image type)
  ///
  /// # Returns
  ///
  /// A slice of MIME type strings.
  Future<List<String>> supportedMimeTypes();
  /// Get the priority of this extractor.
  ///
  /// Higher priority extractors are preferred when multiple extractors
  /// support the same MIME type.
  ///
  /// # Priority Guidelines
  ///
  /// - **0-25**: Fallback/low-quality extractors
  /// - **26-49**: Alternative extractors
  /// - **50**: Default priority (built-in extractors)
  /// - **51-75**: Premium/enhanced extractors
  /// - **76-100**: Specialized/high-priority extractors
  ///
  /// # Returns
  ///
  /// Priority value (default: 50)
  Future<int> priority();
  /// Optional: Check if this extractor can handle a specific file.
  ///
  /// Allows for more sophisticated detection beyond MIME types.
  /// Defaults to `true` (rely on MIME type matching).
  ///
  /// # Arguments
  ///
  /// * `path` - Path to the file to check
  /// * `mime_type` - Detected MIME type
  ///
  /// # Returns
  ///
  /// `true` if the extractor can handle this file, `false` otherwise.
  Future<bool> canHandle(String path, String mimeType);
}

/// Abstract class for the `Renderer` Rust trait.
///
/// Implement this class and register your implementation via:
/// ```dart
/// class MyRenderer implements Renderer {
///   @override
///   Future<String> render(...) async { ... }
/// }
///
/// final impl = createRendererDartImpl(
///   render: (...) => myInstance.render(...),
/// );
/// ```
///
abstract class Renderer {
  /// Render an [`InternalDocument`] to the output format.
  ///
  /// # Arguments
  ///
  /// * `doc` - The internal document to render
  ///
  /// # Returns
  ///
  /// The rendered output as a string.
  ///
  /// # Errors
  ///
  /// Returns an error if rendering fails.
  /// throws anyhow::Error on failure
  Future<String> render(InternalDocumentBridge doc);
}


/// Synchronous extractor trait stub — used by e2e test plugin_api stubs.
abstract class SyncExtractor {}
