// 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

/**
 * Trait for validator plugins.
 *
 * Validators check extraction results for quality, completeness, or correctness.
 * Unlike post-processors, validator errors **fail fast** - if a validator returns
 * an error, the extraction fails immediately.
 *
 * # Use Cases
 *
 * - **Quality Gates**: Ensure extracted content meets minimum quality standards
 * - **Compliance**: Verify content meets regulatory requirements
 * - **Content Filtering**: Reject documents containing unwanted content
 * - **Format Validation**: Verify extracted content structure
 * - **Security Checks**: Scan for malicious content
 *
 * # Error Handling
 *
 * Validator errors are **fatal** - they cause the extraction to fail and bubble up
 * to the caller. Use validators for hard requirements that must be met.
 *
 * For non-fatal checks, use post-processors instead.
 *
 * # Thread Safety
 *
 * Validators must be thread-safe (`Send + Sync`).
 */
interface IValidator {
    fun name(): String
    fun version(): String
    fun initialize() {}
    fun shutdown() {}
    /**
     * Validate an extraction result.
     *
     * Check the extraction result and return `Ok(())` if valid, or an error
     * if validation fails.
     *
     * **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(())
     * }
     * ```
     */
    suspend fun validate(result: ExtractionResult, config: ExtractionConfig)
    /**
     * 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).
     *
     * **Returns:**
     *
     * `true` if the validator should run, `false` to skip.
     */
    fun shouldValidate(result: ExtractionResult, config: ExtractionConfig): Boolean
    /**
     * 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).
     */
    fun priority(): Int
}
