// 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 post-processor plugins.
 *
 * Post-processors transform or enrich extraction results after the initial
 * extraction is complete. They can:
 *
 * - Clean and normalize text
 * - Add metadata (language, keywords, entities)
 * - Split content into chunks
 * - Score quality
 * - Apply custom transformations
 *
 * # Processing Order
 *
 * Post-processors are executed in stage order:
 *
 * 1. **Early** - Language detection, entity extraction
 * 2. **Middle** - Keyword extraction, token reduction
 * 3. **Late** - Custom hooks, final validation
 *
 * Within each stage, processors are executed in registration order.
 *
 * # Error Handling
 *
 * Post-processor errors are non-fatal by default - they're captured in metadata
 * and execution continues. To make errors fatal, return an error from `process()`.
 *
 * # Thread Safety
 *
 * Post-processors must be thread-safe (`Send + Sync`).
 */
interface IPostProcessor {
    fun name(): String
    fun version(): String
    fun initialize() {}
    fun shutdown() {}
    /**
     * 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
     *
     * **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
     *
     *
     * # 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(())
     * }
     * ```
     */
    suspend fun process(result: ExtractionResult, config: ExtractionConfig)
    /**
     * Get the processing stage for this post-processor.
     *
     * Determines when this processor runs in the pipeline.
     *
     * **Returns:**
     *
     * The `ProcessingStage` (Early, Middle, or Late).
     */
    fun 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).
     *
     * **Returns:**
     *
     * `true` if the processor should run, `false` to skip.
     */
    fun shouldProcess(result: ExtractionResult, config: ExtractionConfig): Boolean
    /**
     * Optional: Estimate processing time in milliseconds.
     *
     * Used for logging and debugging. Defaults to 0 (unknown).
     *
     * **Returns:**
     *
     * Estimated processing time in milliseconds.
     */
    fun estimatedDurationMs(result: ExtractionResult): Long
    /**
     * 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.
     */
    fun priority(): Int
}
