kreuzberg 4.0.0.rc2 → 4.0.1

data/vendor/kreuzberg/src/plugins/extractor.rs

@@ -1,1013 +1,1042 @@
-//! Document extractor plugin trait.
-//!
-//! This module defines the trait for implementing custom document extractors.
-
-use crate::Result;
-use crate::core::config::ExtractionConfig;
-use crate::plugins::Plugin;
-use crate::types::ExtractionResult;
-use async_trait::async_trait;
-use std::path::Path;
-use std::sync::Arc;
-
-/// Trait for document extractor plugins.
-///
-/// Implement this trait to add support for new document formats or to override
-/// built-in extraction behavior with custom logic.
-///
-/// # Priority System
-///
-/// When multiple extractors support the same MIME type, the registry selects
-/// the extractor with the highest priority value. Use this to:
-/// - Override built-in extractors (priority > 50)
-/// - Provide fallback extractors (priority < 50)
-/// - Implement specialized extractors for specific use cases
-///
-/// Default priority is 50.
-///
-/// # Thread Safety
-///
-/// Extractors must be thread-safe (`Send + Sync`) to support concurrent extraction.
-///
-/// # Example
-///
-/// ```rust
-/// use kreuzberg::plugins::{Plugin, DocumentExtractor};
-/// use kreuzberg::{Result, ExtractionConfig};
-/// use kreuzberg::types::{ExtractionResult, Metadata};
-/// use async_trait::async_trait;
-/// use std::path::Path;
-///
-/// /// Custom PDF extractor with premium features
-/// struct PremiumPdfExtractor;
-///
-/// impl Plugin for PremiumPdfExtractor {
-///     fn name(&self) -> &str { "premium-pdf" }
-///     fn version(&self) -> String { "2.0.0".to_string() }
-///     fn initialize(&self) -> Result<()> { Ok(()) }
-///     fn shutdown(&self) -> Result<()> { Ok(()) }
-/// }
-///
-/// #[async_trait]
-/// impl DocumentExtractor for PremiumPdfExtractor {
-///     async fn extract_bytes(&self, content: &[u8], mime_type: &str, config: &ExtractionConfig)
-///         -> Result<ExtractionResult> {
-///         // Premium extraction logic with better accuracy
-///         Ok(ExtractionResult {
-///             content: "Premium extracted content".to_string(),
-///             mime_type: mime_type.to_string(),
-///             metadata: Metadata::default(),
-///             tables: vec![],
-///             detected_languages: None,
-///             chunks: None,
-///             images: None,
-///         })
-///     }
-///
-///     async fn extract_file(&self, path: &Path, mime_type: &str, config: &ExtractionConfig)
-///         -> Result<ExtractionResult> {
-///         let bytes = std::fs::read(path)?;
-///         self.extract_bytes(&bytes, mime_type, config).await
-///     }
-///
-///     fn supported_mime_types(&self) -> &[&str] {
-///         &["application/pdf"]
-///     }
-///
-///     fn priority(&self) -> i32 {
-///         100  // Higher than default (50) - will be preferred
-///     }
-/// }
-/// ```
-#[async_trait]
-pub trait DocumentExtractor: Plugin {
-    /// 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 `ExtractionResult` containing the extracted content, metadata, and tables.
-    ///
-    /// # 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
-    ///
-    /// # Example
-    ///
-    /// ```rust,no_run
-    /// # use kreuzberg::plugins::{Plugin, DocumentExtractor};
-    /// # use kreuzberg::{Result, ExtractionConfig};
-    /// # use kreuzberg::types::{ExtractionResult, Metadata};
-    /// # use async_trait::async_trait;
-    /// # use std::path::Path;
-    /// # struct MyExtractor;
-    /// # impl Plugin for MyExtractor {
-    /// #     fn name(&self) -> &str { "my-extractor" }
-    /// #     fn version(&self) -> String { "1.0.0".to_string() }
-    /// #     fn initialize(&self) -> Result<()> { Ok(()) }
-    /// #     fn shutdown(&self) -> Result<()> { Ok(()) }
-    /// # }
-    /// # #[async_trait]
-    /// # impl DocumentExtractor for MyExtractor {
-    /// #     fn supported_mime_types(&self) -> &[&str] { &["text/plain"] }
-    /// #     fn priority(&self) -> i32 { 50 }
-    /// #     async fn extract_file(&self, _: &Path, _: &str, _: &ExtractionConfig) -> Result<ExtractionResult> { todo!() }
-    /// async fn extract_bytes(&self, content: &[u8], mime_type: &str, config: &ExtractionConfig)
-    ///     -> Result<ExtractionResult> {
-    ///     // Parse document
-    ///     let text = String::from_utf8_lossy(content).to_string();
-    ///
-    ///     // Extract metadata
-    ///     let mut metadata = Metadata::default();
-    ///     metadata.additional.insert("byte_count".to_string(), serde_json::json!(content.len()));
-    ///
-    ///     Ok(ExtractionResult {
-    ///         content: text,
-    ///         mime_type: mime_type.to_string(),
-    ///         metadata,
-    ///         tables: vec![],
-    ///         detected_languages: None,
-    ///         chunks: None,
-    ///         images: None,
-    ///     })
-    /// }
-    /// # }
-    /// ```
-    async fn extract_bytes(
-        &self,
-        content: &[u8],
-        mime_type: &str,
-        config: &ExtractionConfig,
-    ) -> Result<ExtractionResult>;
-
-    /// 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
-    ///
-    /// # Errors
-    ///
-    /// Same as `extract_bytes`, plus file I/O errors.
-    ///
-    /// # Example - Custom File Handling
-    ///
-    /// ```rust,no_run
-    /// # use kreuzberg::plugins::{Plugin, DocumentExtractor};
-    /// # use kreuzberg::{Result, ExtractionResult, ExtractionConfig};
-    /// # use kreuzberg::types::Metadata;
-    /// # use async_trait::async_trait;
-    /// # use std::path::Path;
-    /// # struct StreamingExtractor;
-    /// # impl Plugin for StreamingExtractor {
-    /// #     fn name(&self) -> &str { "streaming" }
-    /// #     fn version(&self) -> String { "1.0.0".to_string() }
-    /// #     fn initialize(&self) -> Result<()> { Ok(()) }
-    /// #     fn shutdown(&self) -> Result<()> { Ok(()) }
-    /// # }
-    /// # #[async_trait]
-    /// # impl DocumentExtractor for StreamingExtractor {
-    /// #     fn supported_mime_types(&self) -> &[&str] { &["text/plain"] }
-    /// #     fn priority(&self) -> i32 { 50 }
-    /// #     async fn extract_bytes(&self, _: &[u8], _: &str, _: &ExtractionConfig) -> Result<ExtractionResult> { todo!() }
-    /// /// Override for memory-efficient streaming extraction
-    /// async fn extract_file(&self, path: &Path, mime_type: &str, config: &ExtractionConfig)
-    ///     -> Result<ExtractionResult> {
-    ///     // Stream large files instead of loading entirely into memory
-    ///     let mut content = String::new();
-    ///
-    ///     // Use buffered reader for streaming
-    ///     use std::io::{BufRead, BufReader};
-    ///     let file = std::fs::File::open(path)?;
-    ///     let reader = BufReader::new(file);
-    ///
-    ///     for line in reader.lines() {
-    ///         content.push_str(&line?);
-    ///         content.push('\n');
-    ///     }
-    ///
-    ///     Ok(ExtractionResult {
-    ///         content,
-    ///         mime_type: mime_type.to_string(),
-    ///         metadata: Metadata::default(),
-    ///         tables: vec![],
-    ///         detected_languages: None,
-    ///         chunks: None,
-    ///         images: None,
-    ///     })
-    /// }
-    /// # }
-    /// ```
-    async fn extract_file(&self, path: &Path, mime_type: &str, config: &ExtractionConfig) -> Result<ExtractionResult> {
-        use crate::core::io;
-        let bytes = io::read_file_async(path).await?;
-        self.extract_bytes(&bytes, mime_type, config).await
-    }
-
-    /// 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.
-    ///
-    /// # Example
-    ///
-    /// ```rust
-    /// # use kreuzberg::plugins::{Plugin, DocumentExtractor};
-    /// # use kreuzberg::Result;
-    /// # use async_trait::async_trait;
-    /// # use std::path::Path;
-    /// # struct MultiFormatExtractor;
-    /// # impl Plugin for MultiFormatExtractor {
-    /// #     fn name(&self) -> &str { "multi-format" }
-    /// #     fn version(&self) -> String { "1.0.0".to_string() }
-    /// #     fn initialize(&self) -> Result<()> { Ok(()) }
-    /// #     fn shutdown(&self) -> Result<()> { Ok(()) }
-    /// # }
-    /// # use kreuzberg::{ExtractionResult, ExtractionConfig};
-    /// # #[async_trait]
-    /// # impl DocumentExtractor for MultiFormatExtractor {
-    /// #     fn priority(&self) -> i32 { 50 }
-    /// #     async fn extract_bytes(&self, _: &[u8], _: &str, _: &ExtractionConfig) -> Result<ExtractionResult> { todo!() }
-    /// #     async fn extract_file(&self, _: &Path, _: &str, _: &ExtractionConfig) -> Result<ExtractionResult> { todo!() }
-    /// fn supported_mime_types(&self) -> &[&str] {
-    ///     &[
-    ///         "text/plain",
-    ///         "text/markdown",
-    ///         "application/json",
-    ///         "application/xml",
-    ///         "text/html",
-    ///     ]
-    /// }
-    /// # }
-    /// ```
-    fn supported_mime_types(&self) -> &[&str];
-
-    /// 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)
-    ///
-    /// # Example
-    ///
-    /// ```rust
-    /// # use kreuzberg::plugins::{Plugin, DocumentExtractor};
-    /// # use kreuzberg::Result;
-    /// # use async_trait::async_trait;
-    /// # use std::path::Path;
-    /// # struct FallbackExtractor;
-    /// # impl Plugin for FallbackExtractor {
-    /// #     fn name(&self) -> &str { "fallback" }
-    /// #     fn version(&self) -> String { "1.0.0".to_string() }
-    /// #     fn initialize(&self) -> Result<()> { Ok(()) }
-    /// #     fn shutdown(&self) -> Result<()> { Ok(()) }
-    /// # }
-    /// # use kreuzberg::{ExtractionResult, ExtractionConfig};
-    /// # #[async_trait]
-    /// # impl DocumentExtractor for FallbackExtractor {
-    /// #     fn supported_mime_types(&self) -> &[&str] { &["text/plain"] }
-    /// #     async fn extract_bytes(&self, _: &[u8], _: &str, _: &ExtractionConfig) -> Result<ExtractionResult> { todo!() }
-    /// #     async fn extract_file(&self, _: &Path, _: &str, _: &ExtractionConfig) -> Result<ExtractionResult> { todo!() }
-    /// fn priority(&self) -> i32 {
-    ///     10  // Low priority - only used as fallback
-    /// }
-    /// # }
-    /// ```
-    fn priority(&self) -> i32 {
-        50
-    }
-
-    /// 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.
-    ///
-    /// # Example
-    ///
-    /// ```rust,no_run
-    /// # use kreuzberg::plugins::{Plugin, DocumentExtractor};
-    /// # use kreuzberg::Result;
-    /// # use async_trait::async_trait;
-    /// # use std::path::Path;
-    /// # struct SmartExtractor;
-    /// # impl Plugin for SmartExtractor {
-    /// #     fn name(&self) -> &str { "smart" }
-    /// #     fn version(&self) -> String { "1.0.0".to_string() }
-    /// #     fn initialize(&self) -> Result<()> { Ok(()) }
-    /// #     fn shutdown(&self) -> Result<()> { Ok(()) }
-    /// # }
-    /// # use kreuzberg::{ExtractionResult, ExtractionConfig};
-    /// # #[async_trait]
-    /// # impl DocumentExtractor for SmartExtractor {
-    /// #     fn supported_mime_types(&self) -> &[&str] { &["application/pdf"] }
-    /// #     fn priority(&self) -> i32 { 50 }
-    /// #     async fn extract_bytes(&self, _: &[u8], _: &str, _: &ExtractionConfig) -> Result<ExtractionResult> { todo!() }
-    /// #     async fn extract_file(&self, _: &Path, _: &str, _: &ExtractionConfig) -> Result<ExtractionResult> { todo!() }
-    /// /// Only handle PDFs that are searchable (have text layer)
-    /// fn can_handle(&self, path: &Path, mime_type: &str) -> bool {
-    ///     if mime_type != "application/pdf" {
-    ///         return false;
-    ///     }
-    ///
-    ///     // Check if PDF has text layer (simplified example)
-    ///     // In real implementation, analyze PDF structure here
-    ///     let _ = path; // Use path for PDF analysis
-    ///     true  // Simplified - always accept
-    /// }
-    /// # }
-    /// ```
-    fn can_handle(&self, _path: &Path, _mime_type: &str) -> bool {
-        true
-    }
-}
-
-/// Register a document extractor with the global registry.
-///
-/// The extractor will be registered for all MIME types it supports and will be
-/// available for document extraction. The extractor's `name()` method is used as
-/// the registration name.
-///
-/// # Arguments
-///
-/// * `extractor` - The extractor implementation wrapped in Arc
-///
-/// # Returns
-///
-/// - `Ok(())` if registration succeeded
-/// - `Err(...)` if validation failed or initialization failed
-///
-/// # Errors
-///
-/// - `KreuzbergError::Validation` - Invalid extractor name (empty or contains whitespace)
-/// - Any error from the extractor's `initialize()` method
-///
-/// # Example
-///
-/// ```rust
-/// use kreuzberg::plugins::{Plugin, DocumentExtractor, register_extractor};
-/// use kreuzberg::{Result, ExtractionConfig};
-/// use kreuzberg::types::{ExtractionResult, Metadata};
-/// use async_trait::async_trait;
-/// use std::sync::Arc;
-/// use std::path::Path;
-///
-/// struct CustomExtractor;
-///
-/// impl Plugin for CustomExtractor {
-///     fn name(&self) -> &str { "custom-extractor" }
-///     fn version(&self) -> String { "1.0.0".to_string() }
-///     fn initialize(&self) -> Result<()> { Ok(()) }
-///     fn shutdown(&self) -> Result<()> { Ok(()) }
-/// }
-///
-/// #[async_trait]
-/// impl DocumentExtractor for CustomExtractor {
-///     async fn extract_bytes(&self, content: &[u8], mime_type: &str, _: &ExtractionConfig)
-///         -> Result<ExtractionResult> {
-///         Ok(ExtractionResult {
-///             content: String::from_utf8_lossy(content).to_string(),
-///             mime_type: mime_type.to_string(),
-///             metadata: Metadata::default(),
-///             tables: vec![],
-///             detected_languages: None,
-///             chunks: None,
-///             images: None,
-///         })
-///     }
-///
-///     fn supported_mime_types(&self) -> &[&str] {
-///         &["text/custom"]
-///     }
-/// }
-///
-/// # tokio_test::block_on(async {
-/// let extractor = Arc::new(CustomExtractor);
-/// register_extractor(extractor)?;
-/// # Ok::<(), kreuzberg::KreuzbergError>(())
-/// # });
-/// ```
-pub fn register_extractor(extractor: Arc<dyn DocumentExtractor>) -> crate::Result<()> {
-    use crate::plugins::registry::get_document_extractor_registry;
-
-    let registry = get_document_extractor_registry();
-    let mut registry = registry
-        .write()
-        .expect("~keep Failed to acquire write lock on extractor registry"); // ~keep
-
-    registry.register(extractor)
-}
-
-/// Unregister a document extractor by name.
-///
-/// Removes the extractor from the global registry and calls its `shutdown()` method.
-///
-/// # Arguments
-///
-/// * `name` - Name of the extractor to unregister
-///
-/// # Returns
-///
-/// - `Ok(())` if the extractor was unregistered or didn't exist
-/// - `Err(...)` if the shutdown method failed
-///
-/// # Example
-///
-/// ```rust
-/// use kreuzberg::plugins::unregister_extractor;
-///
-/// # tokio_test::block_on(async {
-/// unregister_extractor("custom-extractor")?;
-/// # Ok::<(), kreuzberg::KreuzbergError>(())
-/// # });
-/// ```
-pub fn unregister_extractor(name: &str) -> crate::Result<()> {
-    use crate::plugins::registry::get_document_extractor_registry;
-
-    let registry = get_document_extractor_registry();
-    let mut registry = registry
-        .write()
-        .expect("~keep Failed to acquire write lock on extractor registry"); // ~keep
-
-    registry.remove(name)
-}
-
-/// List all registered extractors.
-///
-/// Returns the names of all extractors currently registered in the global registry.
-///
-/// # Returns
-///
-/// A vector of extractor names.
-///
-/// # Example
-///
-/// ```rust
-/// use kreuzberg::plugins::list_extractors;
-///
-/// # tokio_test::block_on(async {
-/// let extractors = list_extractors()?;
-/// for name in extractors {
-///     println!("Registered extractor: {}", name);
-/// }
-/// # Ok::<(), kreuzberg::KreuzbergError>(())
-/// # });
-/// ```
-pub fn list_extractors() -> crate::Result<Vec<String>> {
-    use crate::plugins::registry::get_document_extractor_registry;
-
-    let registry = get_document_extractor_registry();
-    let registry = registry
-        .read()
-        .expect("~keep Failed to acquire read lock on extractor registry"); // ~keep
-
-    Ok(registry.list())
-}
-
-/// Clear all extractors from the global registry.
-///
-/// Removes all extractors and calls their `shutdown()` methods.
-///
-/// # Returns
-///
-/// - `Ok(())` if all extractors were cleared successfully
-/// - `Err(...)` if any shutdown method failed
-///
-/// # Example
-///
-/// ```rust
-/// use kreuzberg::plugins::clear_extractors;
-///
-/// # tokio_test::block_on(async {
-/// clear_extractors()?;
-/// # Ok::<(), kreuzberg::KreuzbergError>(())
-/// # });
-/// ```
-pub fn clear_extractors() -> crate::Result<()> {
-    use crate::plugins::registry::get_document_extractor_registry;
-
-    let registry = get_document_extractor_registry();
-    let mut registry = registry
-        .write()
-        .expect("~keep Failed to acquire write lock on extractor registry"); // ~keep
-
-    registry.shutdown_all()
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use serial_test::serial;
-
-    struct MockExtractor {
-        mime_types: Vec<&'static str>,
-        priority: i32,
-    }
-
-    impl Plugin for MockExtractor {
-        fn name(&self) -> &str {
-            "mock-extractor"
-        }
-
-        fn version(&self) -> String {
-            "1.0.0".to_string()
-        }
-
-        fn initialize(&self) -> Result<()> {
-            Ok(())
-        }
-
-        fn shutdown(&self) -> Result<()> {
-            Ok(())
-        }
-    }
-
-    #[async_trait]
-    impl DocumentExtractor for MockExtractor {
-        async fn extract_bytes(
-            &self,
-            content: &[u8],
-            mime_type: &str,
-            _config: &ExtractionConfig,
-        ) -> Result<ExtractionResult> {
-            Ok(ExtractionResult {
-                content: String::from_utf8_lossy(content).to_string(),
-                mime_type: mime_type.to_string(),
-                metadata: crate::types::Metadata::default(),
-                tables: vec![],
-                detected_languages: None,
-                chunks: None,
-                images: None,
-            })
-        }
-
-        fn supported_mime_types(&self) -> &[&str] {
-            &self.mime_types
-        }
-
-        fn priority(&self) -> i32 {
-            self.priority
-        }
-    }
-
-    #[tokio::test]
-    async fn test_document_extractor_extract_bytes() {
-        let extractor = MockExtractor {
-            mime_types: vec!["text/plain"],
-            priority: 50,
-        };
-
-        let config = ExtractionConfig::default();
-        let result = extractor
-            .extract_bytes(b"test content", "text/plain", &config)
-            .await
-            .unwrap();
-
-        assert_eq!(result.content, "test content");
-        assert_eq!(result.mime_type, "text/plain");
-    }
-
-    #[test]
-    fn test_document_extractor_supported_mime_types() {
-        let extractor = MockExtractor {
-            mime_types: vec!["text/plain", "text/markdown"],
-            priority: 50,
-        };
-
-        let supported = extractor.supported_mime_types();
-        assert_eq!(supported.len(), 2);
-        assert!(supported.contains(&"text/plain"));
-        assert!(supported.contains(&"text/markdown"));
-    }
-
-    #[test]
-    fn test_document_extractor_priority() {
-        let low_priority = MockExtractor {
-            mime_types: vec!["text/plain"],
-            priority: 10,
-        };
-
-        let high_priority = MockExtractor {
-            mime_types: vec!["text/plain"],
-            priority: 100,
-        };
-
-        assert_eq!(low_priority.priority(), 10);
-        assert_eq!(high_priority.priority(), 100);
-    }
-
-    #[test]
-    fn test_document_extractor_can_handle_default() {
-        let extractor = MockExtractor {
-            mime_types: vec!["text/plain"],
-            priority: 50,
-        };
-
-        use std::path::PathBuf;
-        let path = PathBuf::from("test.txt");
-
-        assert!(extractor.can_handle(&path, "text/plain"));
-        assert!(extractor.can_handle(&path, "application/pdf"));
-    }
-
-    #[tokio::test]
-    async fn test_document_extractor_extract_file_default_impl() {
-        use std::io::Write;
-        use tempfile::NamedTempFile;
-
-        let extractor = MockExtractor {
-            mime_types: vec!["text/plain"],
-            priority: 50,
-        };
-
-        let mut temp_file = NamedTempFile::new().unwrap();
-        temp_file.write_all(b"file content").unwrap();
-        let path = temp_file.path();
-
-        let config = ExtractionConfig::default();
-        let result = extractor.extract_file(path, "text/plain", &config).await.unwrap();
-
-        assert_eq!(result.content, "file content");
-        assert_eq!(result.mime_type, "text/plain");
-    }
-
-    #[tokio::test]
-    async fn test_document_extractor_empty_content() {
-        let extractor = MockExtractor {
-            mime_types: vec!["text/plain"],
-            priority: 50,
-        };
-
-        let config = ExtractionConfig::default();
-        let result = extractor.extract_bytes(b"", "text/plain", &config).await.unwrap();
-
-        assert_eq!(result.content, "");
-        assert_eq!(result.mime_type, "text/plain");
-    }
-
-    #[tokio::test]
-    async fn test_document_extractor_non_utf8_content() {
-        let extractor = MockExtractor {
-            mime_types: vec!["text/plain"],
-            priority: 50,
-        };
-
-        let invalid_utf8 = vec![0xFF, 0xFE, 0xFD];
-        let config = ExtractionConfig::default();
-        let result = extractor
-            .extract_bytes(&invalid_utf8, "text/plain", &config)
-            .await
-            .unwrap();
-
-        assert!(!result.content.is_empty());
-    }
-
-    #[test]
-    fn test_document_extractor_plugin_interface() {
-        let extractor = MockExtractor {
-            mime_types: vec!["text/plain"],
-            priority: 50,
-        };
-
-        assert_eq!(extractor.name(), "mock-extractor");
-        assert_eq!(extractor.version(), "1.0.0");
-        assert!(extractor.initialize().is_ok());
-        assert!(extractor.shutdown().is_ok());
-    }
-
-    #[test]
-    fn test_document_extractor_default_priority() {
-        struct DefaultPriorityExtractor;
-
-        impl Plugin for DefaultPriorityExtractor {
-            fn name(&self) -> &str {
-                "default"
-            }
-            fn version(&self) -> String {
-                "1.0.0".to_string()
-            }
-            fn initialize(&self) -> Result<()> {
-                Ok(())
-            }
-            fn shutdown(&self) -> Result<()> {
-                Ok(())
-            }
-        }
-
-        #[async_trait]
-        impl DocumentExtractor for DefaultPriorityExtractor {
-            async fn extract_bytes(
-                &self,
-                _content: &[u8],
-                _mime_type: &str,
-                _config: &ExtractionConfig,
-            ) -> Result<ExtractionResult> {
-                Ok(ExtractionResult {
-                    content: String::new(),
-                    mime_type: String::new(),
-                    metadata: crate::types::Metadata::default(),
-                    tables: vec![],
-                    detected_languages: None,
-                    chunks: None,
-                    images: None,
-                })
-            }
-
-            fn supported_mime_types(&self) -> &[&str] {
-                &["text/plain"]
-            }
-        }
-
-        let extractor = DefaultPriorityExtractor;
-        assert_eq!(extractor.priority(), 50);
-    }
-
-    #[test]
-    fn test_document_extractor_empty_mime_types() {
-        let extractor = MockExtractor {
-            mime_types: vec![],
-            priority: 50,
-        };
-
-        assert_eq!(extractor.supported_mime_types().len(), 0);
-    }
-
-    #[test]
-    fn test_document_extractor_wildcard_mime_types() {
-        let extractor = MockExtractor {
-            mime_types: vec!["text/*", "image/*"],
-            priority: 50,
-        };
-
-        let supported = extractor.supported_mime_types();
-        assert_eq!(supported.len(), 2);
-        assert!(supported.contains(&"text/*"));
-        assert!(supported.contains(&"image/*"));
-    }
-
-    #[test]
-    fn test_document_extractor_priority_ranges() {
-        let fallback = MockExtractor {
-            mime_types: vec!["text/plain"],
-            priority: 10,
-        };
-        let alternative = MockExtractor {
-            mime_types: vec!["text/plain"],
-            priority: 40,
-        };
-        let default = MockExtractor {
-            mime_types: vec!["text/plain"],
-            priority: 50,
-        };
-        let premium = MockExtractor {
-            mime_types: vec!["text/plain"],
-            priority: 75,
-        };
-        let specialized = MockExtractor {
-            mime_types: vec!["text/plain"],
-            priority: 100,
-        };
-
-        assert!(fallback.priority() < alternative.priority());
-        assert!(alternative.priority() < default.priority());
-        assert!(default.priority() < premium.priority());
-        assert!(premium.priority() < specialized.priority());
-    }
-
-    #[tokio::test]
-    async fn test_document_extractor_preserves_mime_type() {
-        let extractor = MockExtractor {
-            mime_types: vec!["application/json"],
-            priority: 50,
-        };
-
-        let config = ExtractionConfig::default();
-        let result = extractor
-            .extract_bytes(b"{\"key\":\"value\"}", "application/json", &config)
-            .await
-            .unwrap();
-
-        assert_eq!(result.mime_type, "application/json");
-    }
-
-    #[test]
-    #[serial]
-    fn test_register_extractor() {
-        use std::sync::Arc;
-
-        let extractor = Arc::new(MockExtractor {
-            mime_types: vec!["text/test-register"],
-            priority: 50,
-        });
-        let result = super::register_extractor(extractor);
-        assert!(result.is_ok());
-
-        let _ = super::unregister_extractor("mock-extractor");
-    }
-
-    #[test]
-    #[serial]
-    fn test_unregister_extractor() {
-        use std::sync::Arc;
-
-        let extractor = Arc::new(MockExtractor {
-            mime_types: vec!["text/test-unregister"],
-            priority: 50,
-        });
-        super::register_extractor(extractor).unwrap();
-
-        let result = super::unregister_extractor("mock-extractor");
-        assert!(result.is_ok());
-    }
-
-    #[test]
-    #[serial]
-    fn test_unregister_nonexistent_extractor() {
-        let result = super::unregister_extractor("nonexistent-extractor-xyz");
-        assert!(result.is_ok());
-    }
-
-    #[test]
-    #[serial]
-    fn test_list_extractors() {
-        use std::sync::Arc;
-
-        super::clear_extractors().unwrap();
-
-        let extractor1 = Arc::new(MockExtractor {
-            mime_types: vec!["text/test-list-1"],
-            priority: 50,
-        });
-        let extractor2 = Arc::new(MockExtractor {
-            mime_types: vec!["text/test-list-2"],
-            priority: 51,
-        });
-
-        let list_before = super::list_extractors().unwrap();
-        assert_eq!(list_before.len(), 0);
-
-        super::register_extractor(extractor1).unwrap();
-        super::register_extractor(extractor2).unwrap();
-
-        let list = super::list_extractors().unwrap();
-        assert_eq!(list.len(), 1);
-        assert!(list.contains(&"mock-extractor".to_string()));
-
-        super::unregister_extractor("mock-extractor").unwrap();
-    }
-
-    #[test]
-    #[serial]
-    fn test_clear_extractors() {
-        use std::sync::Arc;
-
-        super::clear_extractors().unwrap();
-
-        let extractor1 = Arc::new(MockExtractor {
-            mime_types: vec!["text/test-clear-1"],
-            priority: 50,
-        });
-        let extractor2 = Arc::new(MockExtractor {
-            mime_types: vec!["text/test-clear-2"],
-            priority: 51,
-        });
-
-        super::register_extractor(extractor1).unwrap();
-        super::register_extractor(extractor2).unwrap();
-
-        let result = super::clear_extractors();
-        assert!(result.is_ok());
-
-        let list = super::list_extractors().unwrap();
-        assert_eq!(list.len(), 0);
-    }
-
-    #[test]
-    #[serial]
-    fn test_register_extractor_with_invalid_name() {
-        use std::sync::Arc;
-
-        struct InvalidNameExtractor;
-        impl Plugin for InvalidNameExtractor {
-            fn name(&self) -> &str {
-                "invalid name with spaces"
-            }
-            fn version(&self) -> String {
-                "1.0.0".to_string()
-            }
-            fn initialize(&self) -> Result<()> {
-                Ok(())
-            }
-            fn shutdown(&self) -> Result<()> {
-                Ok(())
-            }
-        }
-
-        #[async_trait]
-        impl DocumentExtractor for InvalidNameExtractor {
-            async fn extract_bytes(&self, _: &[u8], _: &str, _: &ExtractionConfig) -> Result<ExtractionResult> {
-                Ok(ExtractionResult {
-                    content: String::new(),
-                    mime_type: String::new(),
-                    metadata: crate::types::Metadata::default(),
-                    tables: vec![],
-                    detected_languages: None,
-                    chunks: None,
-                    images: None,
-                })
-            }
-
-            fn supported_mime_types(&self) -> &[&str] {
-                &["text/plain"]
-            }
-        }
-
-        let extractor = Arc::new(InvalidNameExtractor);
-        let result = super::register_extractor(extractor);
-        assert!(matches!(result, Err(crate::KreuzbergError::Validation { .. })));
-    }
-
-    #[test]
-    #[serial]
-    fn test_register_extractor_with_empty_name() {
-        use std::sync::Arc;
-
-        struct EmptyNameExtractor;
-        impl Plugin for EmptyNameExtractor {
-            fn name(&self) -> &str {
-                ""
-            }
-            fn version(&self) -> String {
-                "1.0.0".to_string()
-            }
-            fn initialize(&self) -> Result<()> {
-                Ok(())
-            }
-            fn shutdown(&self) -> Result<()> {
-                Ok(())
-            }
-        }
-
-        #[async_trait]
-        impl DocumentExtractor for EmptyNameExtractor {
-            async fn extract_bytes(&self, _: &[u8], _: &str, _: &ExtractionConfig) -> Result<ExtractionResult> {
-                Ok(ExtractionResult {
-                    content: String::new(),
-                    mime_type: String::new(),
-                    metadata: crate::types::Metadata::default(),
-                    tables: vec![],
-                    detected_languages: None,
-                    chunks: None,
-                    images: None,
-                })
-            }
-
-            fn supported_mime_types(&self) -> &[&str] {
-                &["text/plain"]
-            }
-        }
-
-        let extractor = Arc::new(EmptyNameExtractor);
-        let result = super::register_extractor(extractor);
-        assert!(matches!(result, Err(crate::KreuzbergError::Validation { .. })));
-    }
-}
+//! Document extractor plugin trait.
+//!
+//! This module defines the trait for implementing custom document extractors.
+
+use crate::Result;
+use crate::core::config::ExtractionConfig;
+use crate::plugins::Plugin;
+use crate::types::ExtractionResult;
+use async_trait::async_trait;
+use std::path::Path;
+use std::sync::Arc;
+
+#[cfg(not(feature = "tokio-runtime"))]
+use crate::KreuzbergError;
+
+/// Trait for document extractor plugins.
+///
+/// Implement this trait to add support for new document formats or to override
+/// built-in extraction behavior with custom logic.
+///
+/// # Priority System
+///
+/// When multiple extractors support the same MIME type, the registry selects
+/// the extractor with the highest priority value. Use this to:
+/// - Override built-in extractors (priority > 50)
+/// - Provide fallback extractors (priority < 50)
+/// - Implement specialized extractors for specific use cases
+///
+/// Default priority is 50.
+///
+/// # Thread Safety
+///
+/// Extractors must be thread-safe (`Send + Sync`) to support concurrent extraction.
+///
+/// # Example
+///
+/// ```rust
+/// use kreuzberg::plugins::{Plugin, DocumentExtractor};
+/// use kreuzberg::{Result, ExtractionConfig};
+/// use kreuzberg::types::{ExtractionResult, Metadata};
+/// use async_trait::async_trait;
+/// use std::path::Path;
+///
+/// /// Custom PDF extractor with premium features
+/// struct PremiumPdfExtractor;
+///
+/// impl Plugin for PremiumPdfExtractor {
+///     fn name(&self) -> &str { "premium-pdf" }
+///     fn version(&self) -> String { "2.0.0".to_string() }
+///     fn initialize(&self) -> Result<()> { Ok(()) }
+///     fn shutdown(&self) -> Result<()> { Ok(()) }
+/// }
+///
+/// #[async_trait]
+/// impl DocumentExtractor for PremiumPdfExtractor {
+///     async fn extract_bytes(&self, content: &[u8], mime_type: &str, config: &ExtractionConfig)
+///         -> Result<ExtractionResult> {
+///         // Premium extraction logic with better accuracy
+///         Ok(ExtractionResult {
+///             content: "Premium extracted content".to_string(),
+///             mime_type: mime_type.to_string(),
+///             metadata: Metadata::default(),
+///             tables: vec![],
+///             detected_languages: None,
+///             chunks: None,
+///             images: None,
+///             pages: None,
+///         })
+///     }
+///
+///     async fn extract_file(&self, path: &Path, mime_type: &str, config: &ExtractionConfig)
+///         -> Result<ExtractionResult> {
+///         let bytes = std::fs::read(path)?;
+///         self.extract_bytes(&bytes, mime_type, config).await
+///     }
+///
+///     fn supported_mime_types(&self) -> &[&str] {
+///         &["application/pdf"]
+///     }
+///
+///     fn priority(&self) -> i32 {
+///         100  // Higher than default (50) - will be preferred
+///     }
+/// }
+/// ```
+#[async_trait]
+pub trait DocumentExtractor: Plugin {
+    /// 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 `ExtractionResult` containing the extracted content, metadata, and tables.
+    ///
+    /// # 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
+    ///
+    /// # Example
+    ///
+    /// ```rust,no_run
+    /// # use kreuzberg::plugins::{Plugin, DocumentExtractor};
+    /// # use kreuzberg::{Result, ExtractionConfig};
+    /// # use kreuzberg::types::{ExtractionResult, Metadata};
+    /// # use async_trait::async_trait;
+    /// # use std::path::Path;
+    /// # struct MyExtractor;
+    /// # impl Plugin for MyExtractor {
+    /// #     fn name(&self) -> &str { "my-extractor" }
+    /// #     fn version(&self) -> String { "1.0.0".to_string() }
+    /// #     fn initialize(&self) -> Result<()> { Ok(()) }
+    /// #     fn shutdown(&self) -> Result<()> { Ok(()) }
+    /// # }
+    /// # #[async_trait]
+    /// # impl DocumentExtractor for MyExtractor {
+    /// #     fn supported_mime_types(&self) -> &[&str] { &["text/plain"] }
+    /// #     fn priority(&self) -> i32 { 50 }
+    /// #     async fn extract_file(&self, _: &Path, _: &str, _: &ExtractionConfig) -> Result<ExtractionResult> { todo!() }
+    /// async fn extract_bytes(&self, content: &[u8], mime_type: &str, config: &ExtractionConfig)
+    ///     -> Result<ExtractionResult> {
+    ///     // Parse document
+    ///     let text = String::from_utf8_lossy(content).to_string();
+    ///
+    ///     // Extract metadata
+    ///     let mut metadata = Metadata::default();
+    ///     metadata.additional.insert("byte_count".to_string(), serde_json::json!(content.len()));
+    ///
+    ///     Ok(ExtractionResult {
+    ///         content: text,
+    ///         mime_type: mime_type.to_string(),
+    ///         metadata,
+    ///         tables: vec![],
+    ///         detected_languages: None,
+    ///         chunks: None,
+    ///         images: None,
+    ///         pages: None,
+    ///     })
+    /// }
+    /// # }
+    /// ```
+    async fn extract_bytes(
+        &self,
+        content: &[u8],
+        mime_type: &str,
+        config: &ExtractionConfig,
+    ) -> Result<ExtractionResult>;
+
+    /// 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
+    ///
+    /// # Errors
+    ///
+    /// Same as `extract_bytes`, plus file I/O errors.
+    ///
+    /// # Example - Custom File Handling
+    ///
+    /// ```rust,no_run
+    /// # use kreuzberg::plugins::{Plugin, DocumentExtractor};
+    /// # use kreuzberg::{Result, ExtractionResult, ExtractionConfig};
+    /// # use kreuzberg::types::Metadata;
+    /// # use async_trait::async_trait;
+    /// # use std::path::Path;
+    /// # struct StreamingExtractor;
+    /// # impl Plugin for StreamingExtractor {
+    /// #     fn name(&self) -> &str { "streaming" }
+    /// #     fn version(&self) -> String { "1.0.0".to_string() }
+    /// #     fn initialize(&self) -> Result<()> { Ok(()) }
+    /// #     fn shutdown(&self) -> Result<()> { Ok(()) }
+    /// # }
+    /// # #[async_trait]
+    /// # impl DocumentExtractor for StreamingExtractor {
+    /// #     fn supported_mime_types(&self) -> &[&str] { &["text/plain"] }
+    /// #     fn priority(&self) -> i32 { 50 }
+    /// #     async fn extract_bytes(&self, _: &[u8], _: &str, _: &ExtractionConfig) -> Result<ExtractionResult> { todo!() }
+    /// /// Override for memory-efficient streaming extraction
+    /// async fn extract_file(&self, path: &Path, mime_type: &str, config: &ExtractionConfig)
+    ///     -> Result<ExtractionResult> {
+    ///     // Stream large files instead of loading entirely into memory
+    ///     let mut content = String::new();
+    ///
+    ///     // Use buffered reader for streaming
+    ///     use std::io::{BufRead, BufReader};
+    ///     let file = std::fs::File::open(path)?;
+    ///     let reader = BufReader::new(file);
+    ///
+    ///     for line in reader.lines() {
+    ///         content.push_str(&line?);
+    ///         content.push('\n');
+    ///     }
+    ///
+    ///     Ok(ExtractionResult {
+    ///         content,
+    ///         mime_type: mime_type.to_string(),
+    ///         metadata: Metadata::default(),
+    ///         tables: vec![],
+    ///         detected_languages: None,
+    ///         chunks: None,
+    ///         images: None,
+    ///         pages: None,
+    ///     })
+    /// }
+    /// # }
+    /// ```
+    async fn extract_file(&self, path: &Path, mime_type: &str, config: &ExtractionConfig) -> Result<ExtractionResult> {
+        #[cfg(feature = "tokio-runtime")]
+        {
+            use crate::core::io;
+            let bytes = io::read_file_async(path).await?;
+            self.extract_bytes(&bytes, mime_type, config).await
+        }
+        #[cfg(not(feature = "tokio-runtime"))]
+        {
+            let _ = (path, mime_type, config);
+            Err(KreuzbergError::Other(
+                "File-based extraction requires the tokio-runtime feature".to_string(),
+            ))
+        }
+    }
+
+    /// 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.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// # use kreuzberg::plugins::{Plugin, DocumentExtractor};
+    /// # use kreuzberg::Result;
+    /// # use async_trait::async_trait;
+    /// # use std::path::Path;
+    /// # struct MultiFormatExtractor;
+    /// # impl Plugin for MultiFormatExtractor {
+    /// #     fn name(&self) -> &str { "multi-format" }
+    /// #     fn version(&self) -> String { "1.0.0".to_string() }
+    /// #     fn initialize(&self) -> Result<()> { Ok(()) }
+    /// #     fn shutdown(&self) -> Result<()> { Ok(()) }
+    /// # }
+    /// # use kreuzberg::{ExtractionResult, ExtractionConfig};
+    /// # #[async_trait]
+    /// # impl DocumentExtractor for MultiFormatExtractor {
+    /// #     fn priority(&self) -> i32 { 50 }
+    /// #     async fn extract_bytes(&self, _: &[u8], _: &str, _: &ExtractionConfig) -> Result<ExtractionResult> { todo!() }
+    /// #     async fn extract_file(&self, _: &Path, _: &str, _: &ExtractionConfig) -> Result<ExtractionResult> { todo!() }
+    /// fn supported_mime_types(&self) -> &[&str] {
+    ///     &[
+    ///         "text/plain",
+    ///         "text/markdown",
+    ///         "application/json",
+    ///         "application/xml",
+    ///         "text/html",
+    ///     ]
+    /// }
+    /// # }
+    /// ```
+    fn supported_mime_types(&self) -> &[&str];
+
+    /// 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)
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// # use kreuzberg::plugins::{Plugin, DocumentExtractor};
+    /// # use kreuzberg::Result;
+    /// # use async_trait::async_trait;
+    /// # use std::path::Path;
+    /// # struct FallbackExtractor;
+    /// # impl Plugin for FallbackExtractor {
+    /// #     fn name(&self) -> &str { "fallback" }
+    /// #     fn version(&self) -> String { "1.0.0".to_string() }
+    /// #     fn initialize(&self) -> Result<()> { Ok(()) }
+    /// #     fn shutdown(&self) -> Result<()> { Ok(()) }
+    /// # }
+    /// # use kreuzberg::{ExtractionResult, ExtractionConfig};
+    /// # #[async_trait]
+    /// # impl DocumentExtractor for FallbackExtractor {
+    /// #     fn supported_mime_types(&self) -> &[&str] { &["text/plain"] }
+    /// #     async fn extract_bytes(&self, _: &[u8], _: &str, _: &ExtractionConfig) -> Result<ExtractionResult> { todo!() }
+    /// #     async fn extract_file(&self, _: &Path, _: &str, _: &ExtractionConfig) -> Result<ExtractionResult> { todo!() }
+    /// fn priority(&self) -> i32 {
+    ///     10  // Low priority - only used as fallback
+    /// }
+    /// # }
+    /// ```
+    fn priority(&self) -> i32 {
+        50
+    }
+
+    /// 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.
+    ///
+    /// # Example
+    ///
+    /// ```rust,no_run
+    /// # use kreuzberg::plugins::{Plugin, DocumentExtractor};
+    /// # use kreuzberg::Result;
+    /// # use async_trait::async_trait;
+    /// # use std::path::Path;
+    /// # struct SmartExtractor;
+    /// # impl Plugin for SmartExtractor {
+    /// #     fn name(&self) -> &str { "smart" }
+    /// #     fn version(&self) -> String { "1.0.0".to_string() }
+    /// #     fn initialize(&self) -> Result<()> { Ok(()) }
+    /// #     fn shutdown(&self) -> Result<()> { Ok(()) }
+    /// # }
+    /// # use kreuzberg::{ExtractionResult, ExtractionConfig};
+    /// # #[async_trait]
+    /// # impl DocumentExtractor for SmartExtractor {
+    /// #     fn supported_mime_types(&self) -> &[&str] { &["application/pdf"] }
+    /// #     fn priority(&self) -> i32 { 50 }
+    /// #     async fn extract_bytes(&self, _: &[u8], _: &str, _: &ExtractionConfig) -> Result<ExtractionResult> { todo!() }
+    /// #     async fn extract_file(&self, _: &Path, _: &str, _: &ExtractionConfig) -> Result<ExtractionResult> { todo!() }
+    /// /// Only handle PDFs that are searchable (have text layer)
+    /// fn can_handle(&self, path: &Path, mime_type: &str) -> bool {
+    ///     if mime_type != "application/pdf" {
+    ///         return false;
+    ///     }
+    ///
+    ///     // Check if PDF has text layer (simplified example)
+    ///     // In real implementation, analyze PDF structure here
+    ///     let _ = path; // Use path for PDF analysis
+    ///     true  // Simplified - always accept
+    /// }
+    /// # }
+    /// ```
+    fn can_handle(&self, _path: &Path, _mime_type: &str) -> bool {
+        true
+    }
+
+    /// Attempt to get a reference to this extractor as a SyncExtractor.
+    ///
+    /// Returns None if the extractor doesn't support synchronous extraction.
+    /// This is used for WASM and other sync-only environments.
+    fn as_sync_extractor(&self) -> Option<&dyn crate::extractors::SyncExtractor> {
+        None
+    }
+}
+
+/// Register a document extractor with the global registry.
+///
+/// The extractor will be registered for all MIME types it supports and will be
+/// available for document extraction. The extractor's `name()` method is used as
+/// the registration name.
+///
+/// # Arguments
+///
+/// * `extractor` - The extractor implementation wrapped in Arc
+///
+/// # Returns
+///
+/// - `Ok(())` if registration succeeded
+/// - `Err(...)` if validation failed or initialization failed
+///
+/// # Errors
+///
+/// - `KreuzbergError::Validation` - Invalid extractor name (empty or contains whitespace)
+/// - Any error from the extractor's `initialize()` method
+///
+/// # Example
+///
+/// ```rust
+/// use kreuzberg::plugins::{Plugin, DocumentExtractor, register_extractor};
+/// use kreuzberg::{Result, ExtractionConfig};
+/// use kreuzberg::types::{ExtractionResult, Metadata};
+/// use async_trait::async_trait;
+/// use std::sync::Arc;
+/// use std::path::Path;
+///
+/// struct CustomExtractor;
+///
+/// impl Plugin for CustomExtractor {
+///     fn name(&self) -> &str { "custom-extractor" }
+///     fn version(&self) -> String { "1.0.0".to_string() }
+///     fn initialize(&self) -> Result<()> { Ok(()) }
+///     fn shutdown(&self) -> Result<()> { Ok(()) }
+/// }
+///
+/// #[async_trait]
+/// impl DocumentExtractor for CustomExtractor {
+///     async fn extract_bytes(&self, content: &[u8], mime_type: &str, _: &ExtractionConfig)
+///         -> Result<ExtractionResult> {
+///         Ok(ExtractionResult {
+///             content: String::from_utf8_lossy(content).to_string(),
+///             mime_type: mime_type.to_string(),
+///             metadata: Metadata::default(),
+///             tables: vec![],
+///             detected_languages: None,
+///             chunks: None,
+///             images: None,
+///             pages: None,
+///         })
+///     }
+///
+///     fn supported_mime_types(&self) -> &[&str] {
+///         &["text/custom"]
+///     }
+/// }
+///
+/// # tokio_test::block_on(async {
+/// let extractor = Arc::new(CustomExtractor);
+/// register_extractor(extractor)?;
+/// # Ok::<(), kreuzberg::KreuzbergError>(())
+/// # });
+/// ```
+pub fn register_extractor(extractor: Arc<dyn DocumentExtractor>) -> crate::Result<()> {
+    use crate::plugins::registry::get_document_extractor_registry;
+
+    let registry = get_document_extractor_registry();
+    let mut registry = registry
+        .write()
+        .expect("~keep Failed to acquire write lock on extractor registry"); // ~keep
+
+    registry.register(extractor)
+}
+
+/// Unregister a document extractor by name.
+///
+/// Removes the extractor from the global registry and calls its `shutdown()` method.
+///
+/// # Arguments
+///
+/// * `name` - Name of the extractor to unregister
+///
+/// # Returns
+///
+/// - `Ok(())` if the extractor was unregistered or didn't exist
+/// - `Err(...)` if the shutdown method failed
+///
+/// # Example
+///
+/// ```rust
+/// use kreuzberg::plugins::unregister_extractor;
+///
+/// # tokio_test::block_on(async {
+/// unregister_extractor("custom-extractor")?;
+/// # Ok::<(), kreuzberg::KreuzbergError>(())
+/// # });
+/// ```
+pub fn unregister_extractor(name: &str) -> crate::Result<()> {
+    use crate::plugins::registry::get_document_extractor_registry;
+
+    let registry = get_document_extractor_registry();
+    let mut registry = registry
+        .write()
+        .expect("~keep Failed to acquire write lock on extractor registry"); // ~keep
+
+    registry.remove(name)
+}
+
+/// List all registered extractors.
+///
+/// Returns the names of all extractors currently registered in the global registry.
+///
+/// # Returns
+///
+/// A vector of extractor names.
+///
+/// # Example
+///
+/// ```rust
+/// use kreuzberg::plugins::list_extractors;
+///
+/// # tokio_test::block_on(async {
+/// let extractors = list_extractors()?;
+/// for name in extractors {
+///     println!("Registered extractor: {}", name);
+/// }
+/// # Ok::<(), kreuzberg::KreuzbergError>(())
+/// # });
+/// ```
+pub fn list_extractors() -> crate::Result<Vec<String>> {
+    use crate::plugins::registry::get_document_extractor_registry;
+
+    let registry = get_document_extractor_registry();
+    let registry = registry
+        .read()
+        .expect("~keep Failed to acquire read lock on extractor registry"); // ~keep
+
+    Ok(registry.list())
+}
+
+/// Clear all extractors from the global registry.
+///
+/// Removes all extractors and calls their `shutdown()` methods.
+///
+/// # Returns
+///
+/// - `Ok(())` if all extractors were cleared successfully
+/// - `Err(...)` if any shutdown method failed
+///
+/// # Example
+///
+/// ```rust
+/// use kreuzberg::plugins::clear_extractors;
+///
+/// # tokio_test::block_on(async {
+/// clear_extractors()?;
+/// # Ok::<(), kreuzberg::KreuzbergError>(())
+/// # });
+/// ```
+pub fn clear_extractors() -> crate::Result<()> {
+    use crate::plugins::registry::get_document_extractor_registry;
+
+    let registry = get_document_extractor_registry();
+    let mut registry = registry
+        .write()
+        .expect("~keep Failed to acquire write lock on extractor registry"); // ~keep
+
+    registry.shutdown_all()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serial_test::serial;
+
+    struct MockExtractor {
+        mime_types: Vec<&'static str>,
+        priority: i32,
+    }
+
+    impl Plugin for MockExtractor {
+        fn name(&self) -> &str {
+            "mock-extractor"
+        }
+
+        fn version(&self) -> String {
+            "1.0.0".to_string()
+        }
+
+        fn initialize(&self) -> Result<()> {
+            Ok(())
+        }
+
+        fn shutdown(&self) -> Result<()> {
+            Ok(())
+        }
+    }
+
+    #[async_trait]
+    impl DocumentExtractor for MockExtractor {
+        async fn extract_bytes(
+            &self,
+            content: &[u8],
+            mime_type: &str,
+            _config: &ExtractionConfig,
+        ) -> Result<ExtractionResult> {
+            Ok(ExtractionResult {
+                content: String::from_utf8_lossy(content).to_string(),
+                mime_type: mime_type.to_string(),
+                metadata: crate::types::Metadata::default(),
+                tables: vec![],
+                detected_languages: None,
+                chunks: None,
+                images: None,
+                pages: None,
+            })
+        }
+
+        fn supported_mime_types(&self) -> &[&str] {
+            &self.mime_types
+        }
+
+        fn priority(&self) -> i32 {
+            self.priority
+        }
+    }
+
+    #[tokio::test]
+    async fn test_document_extractor_extract_bytes() {
+        let extractor = MockExtractor {
+            mime_types: vec!["text/plain"],
+            priority: 50,
+        };
+
+        let config = ExtractionConfig::default();
+        let result = extractor
+            .extract_bytes(b"test content", "text/plain", &config)
+            .await
+            .unwrap();
+
+        assert_eq!(result.content, "test content");
+        assert_eq!(result.mime_type, "text/plain");
+    }
+
+    #[test]
+    fn test_document_extractor_supported_mime_types() {
+        let extractor = MockExtractor {
+            mime_types: vec!["text/plain", "text/markdown"],
+            priority: 50,
+        };
+
+        let supported = extractor.supported_mime_types();
+        assert_eq!(supported.len(), 2);
+        assert!(supported.contains(&"text/plain"));
+        assert!(supported.contains(&"text/markdown"));
+    }
+
+    #[test]
+    fn test_document_extractor_priority() {
+        let low_priority = MockExtractor {
+            mime_types: vec!["text/plain"],
+            priority: 10,
+        };
+
+        let high_priority = MockExtractor {
+            mime_types: vec!["text/plain"],
+            priority: 100,
+        };
+
+        assert_eq!(low_priority.priority(), 10);
+        assert_eq!(high_priority.priority(), 100);
+    }
+
+    #[test]
+    fn test_document_extractor_can_handle_default() {
+        let extractor = MockExtractor {
+            mime_types: vec!["text/plain"],
+            priority: 50,
+        };
+
+        use std::path::PathBuf;
+        let path = PathBuf::from("test.txt");
+
+        assert!(extractor.can_handle(&path, "text/plain"));
+        assert!(extractor.can_handle(&path, "application/pdf"));
+    }
+
+    #[tokio::test]
+    async fn test_document_extractor_extract_file_default_impl() {
+        use std::io::Write;
+        use tempfile::NamedTempFile;
+
+        let extractor = MockExtractor {
+            mime_types: vec!["text/plain"],
+            priority: 50,
+        };
+
+        let mut temp_file = NamedTempFile::new().unwrap();
+        temp_file.write_all(b"file content").unwrap();
+        let path = temp_file.path();
+
+        let config = ExtractionConfig::default();
+        let result = extractor.extract_file(path, "text/plain", &config).await.unwrap();
+
+        assert_eq!(result.content, "file content");
+        assert_eq!(result.mime_type, "text/plain");
+    }
+
+    #[tokio::test]
+    async fn test_document_extractor_empty_content() {
+        let extractor = MockExtractor {
+            mime_types: vec!["text/plain"],
+            priority: 50,
+        };
+
+        let config = ExtractionConfig::default();
+        let result = extractor.extract_bytes(b"", "text/plain", &config).await.unwrap();
+
+        assert_eq!(result.content, "");
+        assert_eq!(result.mime_type, "text/plain");
+    }
+
+    #[tokio::test]
+    async fn test_document_extractor_non_utf8_content() {
+        let extractor = MockExtractor {
+            mime_types: vec!["text/plain"],
+            priority: 50,
+        };
+
+        let invalid_utf8 = vec![0xFF, 0xFE, 0xFD];
+        let config = ExtractionConfig::default();
+        let result = extractor
+            .extract_bytes(&invalid_utf8, "text/plain", &config)
+            .await
+            .unwrap();
+
+        assert!(!result.content.is_empty());
+    }
+
+    #[test]
+    fn test_document_extractor_plugin_interface() {
+        let extractor = MockExtractor {
+            mime_types: vec!["text/plain"],
+            priority: 50,
+        };
+
+        assert_eq!(extractor.name(), "mock-extractor");
+        assert_eq!(extractor.version(), "1.0.0");
+        assert!(extractor.initialize().is_ok());
+        assert!(extractor.shutdown().is_ok());
+    }
+
+    #[test]
+    fn test_document_extractor_default_priority() {
+        struct DefaultPriorityExtractor;
+
+        impl Plugin for DefaultPriorityExtractor {
+            fn name(&self) -> &str {
+                "default"
+            }
+            fn version(&self) -> String {
+                "1.0.0".to_string()
+            }
+            fn initialize(&self) -> Result<()> {
+                Ok(())
+            }
+            fn shutdown(&self) -> Result<()> {
+                Ok(())
+            }
+        }
+
+        #[async_trait]
+        impl DocumentExtractor for DefaultPriorityExtractor {
+            async fn extract_bytes(
+                &self,
+                _content: &[u8],
+                _mime_type: &str,
+                _config: &ExtractionConfig,
+            ) -> Result<ExtractionResult> {
+                Ok(ExtractionResult {
+                    content: String::new(),
+                    mime_type: String::new(),
+                    metadata: crate::types::Metadata::default(),
+                    tables: vec![],
+                    detected_languages: None,
+                    chunks: None,
+                    images: None,
+                    pages: None,
+                })
+            }
+
+            fn supported_mime_types(&self) -> &[&str] {
+                &["text/plain"]
+            }
+        }
+
+        let extractor = DefaultPriorityExtractor;
+        assert_eq!(extractor.priority(), 50);
+    }
+
+    #[test]
+    fn test_document_extractor_empty_mime_types() {
+        let extractor = MockExtractor {
+            mime_types: vec![],
+            priority: 50,
+        };
+
+        assert_eq!(extractor.supported_mime_types().len(), 0);
+    }
+
+    #[test]
+    fn test_document_extractor_wildcard_mime_types() {
+        let extractor = MockExtractor {
+            mime_types: vec!["text/*", "image/*"],
+            priority: 50,
+        };
+
+        let supported = extractor.supported_mime_types();
+        assert_eq!(supported.len(), 2);
+        assert!(supported.contains(&"text/*"));
+        assert!(supported.contains(&"image/*"));
+    }
+
+    #[test]
+    fn test_document_extractor_priority_ranges() {
+        let fallback = MockExtractor {
+            mime_types: vec!["text/plain"],
+            priority: 10,
+        };
+        let alternative = MockExtractor {
+            mime_types: vec!["text/plain"],
+            priority: 40,
+        };
+        let default = MockExtractor {
+            mime_types: vec!["text/plain"],
+            priority: 50,
+        };
+        let premium = MockExtractor {
+            mime_types: vec!["text/plain"],
+            priority: 75,
+        };
+        let specialized = MockExtractor {
+            mime_types: vec!["text/plain"],
+            priority: 100,
+        };
+
+        assert!(fallback.priority() < alternative.priority());
+        assert!(alternative.priority() < default.priority());
+        assert!(default.priority() < premium.priority());
+        assert!(premium.priority() < specialized.priority());
+    }
+
+    #[tokio::test]
+    async fn test_document_extractor_preserves_mime_type() {
+        let extractor = MockExtractor {
+            mime_types: vec!["application/json"],
+            priority: 50,
+        };
+
+        let config = ExtractionConfig::default();
+        let result = extractor
+            .extract_bytes(b"{\"key\":\"value\"}", "application/json", &config)
+            .await
+            .unwrap();
+
+        assert_eq!(result.mime_type, "application/json");
+    }
+
+    #[test]
+    #[serial]
+    fn test_register_extractor() {
+        use std::sync::Arc;
+
+        let extractor = Arc::new(MockExtractor {
+            mime_types: vec!["text/test-register"],
+            priority: 50,
+        });
+        let result = super::register_extractor(extractor);
+        assert!(result.is_ok());
+
+        let _ = super::unregister_extractor("mock-extractor");
+    }
+
+    #[test]
+    #[serial]
+    fn test_unregister_extractor() {
+        use std::sync::Arc;
+
+        let extractor = Arc::new(MockExtractor {
+            mime_types: vec!["text/test-unregister"],
+            priority: 50,
+        });
+        super::register_extractor(extractor).unwrap();
+
+        let result = super::unregister_extractor("mock-extractor");
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    #[serial]
+    fn test_unregister_nonexistent_extractor() {
+        let result = super::unregister_extractor("nonexistent-extractor-xyz");
+        assert!(result.is_ok());
+    }
+
+    #[test]
+    #[serial]
+    fn test_list_extractors() {
+        use std::sync::Arc;
+
+        super::clear_extractors().unwrap();
+
+        let extractor1 = Arc::new(MockExtractor {
+            mime_types: vec!["text/test-list-1"],
+            priority: 50,
+        });
+        let extractor2 = Arc::new(MockExtractor {
+            mime_types: vec!["text/test-list-2"],
+            priority: 51,
+        });
+
+        let list_before = super::list_extractors().unwrap();
+        assert_eq!(list_before.len(), 0);
+
+        super::register_extractor(extractor1).unwrap();
+        super::register_extractor(extractor2).unwrap();
+
+        let list = super::list_extractors().unwrap();
+        assert_eq!(list.len(), 1);
+        assert!(list.contains(&"mock-extractor".to_string()));
+
+        super::unregister_extractor("mock-extractor").unwrap();
+    }
+
+    #[test]
+    #[serial]
+    fn test_clear_extractors() {
+        use std::sync::Arc;
+
+        super::clear_extractors().unwrap();
+
+        let extractor1 = Arc::new(MockExtractor {
+            mime_types: vec!["text/test-clear-1"],
+            priority: 50,
+        });
+        let extractor2 = Arc::new(MockExtractor {
+            mime_types: vec!["text/test-clear-2"],
+            priority: 51,
+        });
+
+        super::register_extractor(extractor1).unwrap();
+        super::register_extractor(extractor2).unwrap();
+
+        let result = super::clear_extractors();
+        assert!(result.is_ok());
+
+        let list = super::list_extractors().unwrap();
+        assert_eq!(list.len(), 0);
+    }
+
+    #[test]
+    #[serial]
+    fn test_register_extractor_with_invalid_name() {
+        use std::sync::Arc;
+
+        struct InvalidNameExtractor;
+        impl Plugin for InvalidNameExtractor {
+            fn name(&self) -> &str {
+                "invalid name with spaces"
+            }
+            fn version(&self) -> String {
+                "1.0.0".to_string()
+            }
+            fn initialize(&self) -> Result<()> {
+                Ok(())
+            }
+            fn shutdown(&self) -> Result<()> {
+                Ok(())
+            }
+        }
+
+        #[async_trait]
+        impl DocumentExtractor for InvalidNameExtractor {
+            async fn extract_bytes(&self, _: &[u8], _: &str, _: &ExtractionConfig) -> Result<ExtractionResult> {
+                Ok(ExtractionResult {
+                    content: String::new(),
+                    mime_type: String::new(),
+                    metadata: crate::types::Metadata::default(),
+                    tables: vec![],
+                    detected_languages: None,
+                    chunks: None,
+                    images: None,
+                    pages: None,
+                })
+            }
+
+            fn supported_mime_types(&self) -> &[&str] {
+                &["text/plain"]
+            }
+        }
+
+        let extractor = Arc::new(InvalidNameExtractor);
+        let result = super::register_extractor(extractor);
+        assert!(matches!(result, Err(crate::KreuzbergError::Validation { .. })));
+    }
+
+    #[test]
+    #[serial]
+    fn test_register_extractor_with_empty_name() {
+        use std::sync::Arc;
+
+        struct EmptyNameExtractor;
+        impl Plugin for EmptyNameExtractor {
+            fn name(&self) -> &str {
+                ""
+            }
+            fn version(&self) -> String {
+                "1.0.0".to_string()
+            }
+            fn initialize(&self) -> Result<()> {
+                Ok(())
+            }
+            fn shutdown(&self) -> Result<()> {
+                Ok(())
+            }
+        }
+
+        #[async_trait]
+        impl DocumentExtractor for EmptyNameExtractor {
+            async fn extract_bytes(&self, _: &[u8], _: &str, _: &ExtractionConfig) -> Result<ExtractionResult> {
+                Ok(ExtractionResult {
+                    content: String::new(),
+                    mime_type: String::new(),
+                    metadata: crate::types::Metadata::default(),
+                    tables: vec![],
+                    detected_languages: None,
+                    chunks: None,
+                    images: None,
+                    pages: None,
+                })
+            }
+
+            fn supported_mime_types(&self) -> &[&str] {
+                &["text/plain"]
+            }
+        }
+
+        let extractor = Arc::new(EmptyNameExtractor);
+        let result = super::register_extractor(extractor);
+        assert!(matches!(result, Err(crate::KreuzbergError::Validation { .. })));
+    }
+}