fix: pass ExtractionResult instances to Python plugins, fix CI workflows

- Fix PostProcessor and Validator bridges to pass ExtractionResult class
  instances instead of plain dicts, matching the documented Python API
- Support both ExtractionResult (attribute access) and dict returns for
  backward compatibility in PostProcessor bridge
- Update all Python doc snippets to use attribute access consistently
- Add golangci-lint installation to ci-go.yaml for e2e test generation
- Fix Deno e2e helpers to handle undefined images/pages/elements fields
- Add lint script to wasm-workers e2e package.json

Author: Goldziher

.github/workflows/ci-go.yaml

@@ -599,6 +599,12 @@ jobs:
           PKG_CONFIG_PATH: ${{ env.PKG_CONFIG_PATH }}
           GO_TEST_FLAGS: ${{ runner.os == 'Windows' && '-ldflags=-linkmode=external -extldflags=-Wl,--verbose' || '' }}
 
+      - name: Install golangci-lint
+        shell: bash
+        run: |
+          curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b "$(go env GOPATH)/bin" v2.9.0
+          echo "$(go env GOPATH)/bin" >> "$GITHUB_PATH"
+
       - name: Generate Go E2E tests
         shell: bash
         run: |

crates/kreuzberg-py/src/plugins/processor_bridge.rs

@@ -14,7 +14,9 @@ use kreuzberg::plugins::{Plugin, PostProcessor, ProcessingStage};
 use kreuzberg::types::ExtractionResult;
 use kreuzberg::{KreuzbergError, Result};
 
-use super::common::{json_value_to_py, python_to_json, validate_plugin_object};
+use crate::types::ExtractionResult as PyExtractionResult;
+
+use super::common::{python_to_json, validate_plugin_object};
 
 /// Wrapper that makes a Python PostProcessor usable from Rust.
 ///
@@ -133,26 +135,29 @@ impl PostProcessor for PythonPostProcessor {
             Python::attach(|py| {
                 let obj = self.python_obj.bind(py);
 
-                let result_dict = extraction_result_to_dict(py, result).map_err(|e| KreuzbergError::Plugin {
-                    message: format!("Failed to convert ExtractionResult to Python dict: {}", e),
+                // Convert Rust ExtractionResult to Python ExtractionResult class instance
+                let py_extraction_result =
+                    PyExtractionResult::from_rust(result.clone(), py, None, None).map_err(|e| {
+                        KreuzbergError::Plugin {
+                            message: format!("Failed to convert ExtractionResult to Python: {}", e),
+                            plugin_name: processor_name.clone(),
+                        }
+                    })?;
+
+                let py_result_obj = Py::new(py, py_extraction_result).map_err(|e| KreuzbergError::Plugin {
+                    message: format!("Failed to create Python ExtractionResult: {}", e),
                     plugin_name: processor_name.clone(),
                 })?;
 
-                let py_result = result_dict.bind(py);
                 let processed = obj
-                    .call_method1("process", (py_result,))
+                    .call_method1("process", (py_result_obj,))
                     .map_err(|e| KreuzbergError::Plugin {
                         message: format!("Python PostProcessor '{}' failed during process: {}", processor_name, e),
                         plugin_name: processor_name.clone(),
                     })?;
 
-                let processed_dict = processed.cast_into::<PyDict>().map_err(|e| KreuzbergError::Plugin {
-                    message: format!("PostProcessor did not return a dict: {}", e),
-                    plugin_name: processor_name.clone(),
-                })?;
-
                 let mut updated_result = result.clone();
-                merge_dict_to_extraction_result(py, &processed_dict, &mut updated_result)?;
+                merge_processed_result(py, &processed, &mut updated_result)?;
 
                 Ok::<ExtractionResult, KreuzbergError>(updated_result)
             })
@@ -167,67 +172,45 @@ impl PostProcessor for PythonPostProcessor {
     }
 }
 
-/// Convert Rust ExtractionResult to Python dict.
+/// Merge a processed Python result back into a Rust ExtractionResult.
 ///
-/// This creates a Python dict that can be passed to Python processors:
-/// ```python
-/// {
-///     "content": "extracted text",
-///     "mime_type": "application/pdf",
-///     "metadata": {"key": "value"},
-///     "tables": [...]
-/// }
-/// ```
-fn extraction_result_to_dict(py: Python<'_>, result: &ExtractionResult) -> PyResult<Py<PyDict>> {
-    let dict = PyDict::new(py);
-
-    dict.set_item("content", &result.content)?;
-
-    dict.set_item("mime_type", &result.mime_type)?;
-
-    let metadata_dict = PyDict::new(py);
-
-    if let Some(title) = &result.metadata.title {
-        metadata_dict.set_item("title", title)?;
-    }
-    if let Some(subject) = &result.metadata.subject {
-        metadata_dict.set_item("subject", subject)?;
-    }
-    if let Some(authors) = &result.metadata.authors {
-        metadata_dict.set_item("authors", authors)?;
-    }
-    if let Some(keywords) = &result.metadata.keywords {
-        metadata_dict.set_item("keywords", keywords)?;
-    }
-    if let Some(language) = &result.metadata.language {
-        metadata_dict.set_item("language", language)?;
-    }
-    if let Some(created_at) = &result.metadata.created_at {
-        metadata_dict.set_item("created_at", created_at)?;
-    }
-    if let Some(modified_at) = &result.metadata.modified_at {
-        metadata_dict.set_item("modified_at", modified_at)?;
-    }
-    if let Some(created_by) = &result.metadata.created_by {
-        metadata_dict.set_item("created_by", created_by)?;
-    }
-    if let Some(modified_by) = &result.metadata.modified_by {
-        metadata_dict.set_item("modified_by", modified_by)?;
-    }
-    if let Some(created_at) = &result.metadata.created_at {
-        metadata_dict.set_item("created_at", created_at)?;
+/// Supports both ExtractionResult class instances (attribute access) and
+/// plain dicts (dict-style access) for backward compatibility.
+fn merge_processed_result(py: Python<'_>, processed: &Bound<'_, PyAny>, result: &mut ExtractionResult) -> Result<()> {
+    // If processor returned a dict, use dict-style access for backward compatibility
+    if let Ok(dict) = processed.cast::<PyDict>() {
+        return merge_dict_to_extraction_result(py, dict, result);
     }
 
-    for (key, value) in &result.metadata.additional {
-        let py_value = json_value_to_py(py, value)?;
-        metadata_dict.set_item(key, py_value)?;
+    // Use attribute access (ExtractionResult or duck-typed object)
+    if let Ok(content) = processed.getattr("content")
+        && !content.is_none()
+    {
+        result.content = content.extract().map_err(|e| KreuzbergError::Plugin {
+            message: format!("PostProcessor returned invalid 'content': {}", e),
+            plugin_name: "python".to_string(),
+        })?;
     }
 
-    dict.set_item("metadata", metadata_dict)?;
+    if let Ok(metadata) = processed.getattr("metadata")
+        && !metadata.is_none()
+        && let Ok(meta_dict) = metadata.cast::<PyDict>()
+    {
+        for (key, value) in meta_dict.iter() {
+            let key_str: String = key.extract().map_err(|_| KreuzbergError::Plugin {
+                message: "Metadata keys must be strings".to_string(),
+                plugin_name: "python".to_string(),
+            })?;
 
-    dict.set_item("tables", pyo3::types::PyList::empty(py))?;
+            let json_value = python_to_json(&value)?;
+            result
+                .metadata
+                .additional
+                .insert(std::borrow::Cow::Owned(key_str), json_value);
+        }
+    }
 
-    Ok(dict.unbind())
+    Ok(())
 }
 
 /// Merge Python dict back into ExtractionResult.
@@ -288,7 +271,7 @@ fn merge_dict_to_extraction_result(
 ///
 /// The Python processor must implement:
 /// - `name() -> str` - Return processor name
-/// - `process(result: dict) -> dict` - Process and enrich the extraction result
+/// - `process(result: ExtractionResult) -> ExtractionResult` - Process and enrich the extraction result
 ///
 /// # Optional Methods
 ///
@@ -300,7 +283,7 @@ fn merge_dict_to_extraction_result(
 /// # Example
 ///
 /// ```python
-/// from kreuzberg import register_post_processor
+/// from kreuzberg import register_post_processor, ExtractionResult
 ///
 /// class EntityExtractor:
 ///     def name(self) -> str:
@@ -309,10 +292,10 @@ fn merge_dict_to_extraction_result(
 ///     def processing_stage(self) -> str:
 ///         return "early"
 ///
-///     def process(self, result: dict) -> dict:
-///         # Extract entities from result["content"]
+///     def process(self, result: ExtractionResult) -> ExtractionResult:
+///         # Extract entities from result.content
 ///         entities = {"PERSON": ["John Doe"], "ORG": ["Microsoft"]}
-///         result["metadata"]["entities"] = entities
+///         result.metadata["entities"] = entities
 ///         return result
 ///
 /// register_post_processor(EntityExtractor())
@@ -369,7 +352,7 @@ pub fn register_post_processor(py: Python<'_>, processor: Py<PyAny>) -> PyResult
 ///     def name(self) -> str:
 ///         return "my_processor"
 ///
-///     def process(self, result: dict) -> dict:
+///     def process(self, result: ExtractionResult) -> ExtractionResult:
 ///         return result
 ///
 /// register_post_processor(MyProcessor())
@@ -444,7 +427,7 @@ pub fn clear_post_processors(py: Python<'_>) -> PyResult<()> {
 ///     def name(self) -> str:
 ///         return "my_processor"
 ///
-///     def process(self, result: dict) -> dict:
+///     def process(self, result: ExtractionResult) -> ExtractionResult:
 ///         return result
 ///
 /// # Register processor

crates/kreuzberg-py/src/plugins/validator_bridge.rs

@@ -5,7 +5,6 @@
 
 use async_trait::async_trait;
 use pyo3::prelude::*;
-use pyo3::types::PyDict;
 use std::sync::Arc;
 
 use kreuzberg::core::config::ExtractionConfig;
@@ -14,7 +13,9 @@ use kreuzberg::plugins::{Plugin, Validator};
 use kreuzberg::types::ExtractionResult;
 use kreuzberg::{KreuzbergError, Result};
 
-use super::common::{json_value_to_py, validate_plugin_object};
+use crate::types::ExtractionResult as PyExtractionResult;
+
+use super::common::validate_plugin_object;
 
 /// Wrapper that makes a Python Validator usable from Rust.
 ///
@@ -127,13 +128,21 @@ impl Validator for PythonValidator {
             Python::attach(|py| {
                 let obj = self.python_obj.bind(py);
 
-                let result_dict = extraction_result_to_dict(py, result).map_err(|e| KreuzbergError::Plugin {
-                    message: format!("Failed to convert ExtractionResult to Python dict: {}", e),
+                // Convert Rust ExtractionResult to Python ExtractionResult class instance
+                let py_extraction_result =
+                    PyExtractionResult::from_rust(result.clone(), py, None, None).map_err(|e| {
+                        KreuzbergError::Plugin {
+                            message: format!("Failed to convert ExtractionResult to Python: {}", e),
+                            plugin_name: validator_name.clone(),
+                        }
+                    })?;
+
+                let py_result_obj = Py::new(py, py_extraction_result).map_err(|e| KreuzbergError::Plugin {
+                    message: format!("Failed to create Python ExtractionResult: {}", e),
                     plugin_name: validator_name.clone(),
                 })?;
 
-                let py_result = result_dict.bind(py);
-                obj.call_method1("validate", (py_result,)).map_err(|e| {
+                obj.call_method1("validate", (py_result_obj,)).map_err(|e| {
                     let is_validation_error = e.is_instance_of::<pyo3::exceptions::PyValueError>(py)
                         || e.get_type(py)
                             .name()
@@ -180,9 +189,10 @@ impl Validator for PythonValidator {
                 .unwrap_or(false);
 
             if has_should_validate {
-                let result_dict = extraction_result_to_dict(py, result).ok()?;
-                let py_result = result_dict.bind(py);
-                obj.call_method1("should_validate", (py_result,))
+                let py_extraction_result =
+                    PyExtractionResult::from_rust(result.clone(), py, None, None).ok()?;
+                let py_result_obj = Py::new(py, py_extraction_result).ok()?;
+                obj.call_method1("should_validate", (py_result_obj,))
                     .and_then(|v| v.extract::<bool>())
                     .ok()
             } else {
@@ -197,69 +207,6 @@ impl Validator for PythonValidator {
     }
 }
 
-/// Convert Rust ExtractionResult to Python dict.
-///
-/// This creates a Python dict that can be passed to Python validators:
-/// ```python
-/// {
-///     "content": "extracted text",
-///     "mime_type": "application/pdf",
-///     "metadata": {"key": "value"},
-///     "tables": [...]
-/// }
-/// ```
-fn extraction_result_to_dict(py: Python<'_>, result: &ExtractionResult) -> PyResult<Py<PyDict>> {
-    let dict = PyDict::new(py);
-
-    dict.set_item("content", &result.content)?;
-
-    dict.set_item("mime_type", &result.mime_type)?;
-
-    let metadata_dict = PyDict::new(py);
-
-    if let Some(title) = &result.metadata.title {
-        metadata_dict.set_item("title", title)?;
-    }
-    if let Some(subject) = &result.metadata.subject {
-        metadata_dict.set_item("subject", subject)?;
-    }
-    if let Some(authors) = &result.metadata.authors {
-        metadata_dict.set_item("authors", authors)?;
-    }
-    if let Some(keywords) = &result.metadata.keywords {
-        metadata_dict.set_item("keywords", keywords)?;
-    }
-    if let Some(language) = &result.metadata.language {
-        metadata_dict.set_item("language", language)?;
-    }
-    if let Some(created_at) = &result.metadata.created_at {
-        metadata_dict.set_item("created_at", created_at)?;
-    }
-    if let Some(modified_at) = &result.metadata.modified_at {
-        metadata_dict.set_item("modified_at", modified_at)?;
-    }
-    if let Some(created_by) = &result.metadata.created_by {
-        metadata_dict.set_item("created_by", created_by)?;
-    }
-    if let Some(modified_by) = &result.metadata.modified_by {
-        metadata_dict.set_item("modified_by", modified_by)?;
-    }
-    if let Some(created_at) = &result.metadata.created_at {
-        metadata_dict.set_item("created_at", created_at)?;
-    }
-
-    for (key, value) in &result.metadata.additional {
-        let py_value = json_value_to_py(py, value)?;
-        metadata_dict.set_item(key, py_value)?;
-    }
-
-    dict.set_item("metadata", metadata_dict)?;
-
-    dict.set_item("tables", pyo3::types::PyList::empty(py))?;
-
-    Ok(dict.unbind())
-}
-
 /// Register a Python Validator with the Rust core.
 ///
 /// This function validates the Python validator object, wraps it in a Rust
@@ -275,11 +222,11 @@ fn extraction_result_to_dict(py: Python<'_>, result: &ExtractionResult) -> PyRes
 ///
 /// The Python validator must implement:
 /// - `name() -> str` - Return validator name
-/// - `validate(result: dict) -> None` - Validate the extraction result (raise error to fail)
+/// - `validate(result: ExtractionResult) -> None` - Validate the extraction result (raise error to fail)
 ///
 /// # Optional Methods
 ///
-/// - `should_validate(result: dict) -> bool` - Check if validator should run (defaults to True)
+/// - `should_validate(result: ExtractionResult) -> bool` - Check if validator should run (defaults to True)
 /// - `priority() -> int` - Return priority (defaults to 50, higher runs first)
 /// - `initialize()` - Called when validator is registered
 /// - `shutdown()` - Called when validator is unregistered
@@ -288,7 +235,7 @@ fn extraction_result_to_dict(py: Python<'_>, result: &ExtractionResult) -> PyRes
 /// # Example
 ///
 /// ```python
-/// from kreuzberg import register_validator
+/// from kreuzberg import register_validator, ExtractionResult
 /// from kreuzberg.exceptions import ValidationError
 ///
 /// class MinLengthValidator:
@@ -298,10 +245,10 @@ fn extraction_result_to_dict(py: Python<'_>, result: &ExtractionResult) -> PyRes
 ///     def priority(self) -> int:
 ///         return 100  # Run early
 ///
-///     def validate(self, result: dict) -> None:
-///         if len(result["content"]) < 100:
+///     def validate(self, result: ExtractionResult) -> None:
+///         if len(result.content) < 100:
 ///             raise ValidationError(
-///                 f"Content too short: {len(result['content'])} < 100 characters"
+///                 f"Content too short: {len(result.content)} < 100 characters"
 ///             )
 ///
 /// register_validator(MinLengthValidator())
@@ -358,7 +305,7 @@ pub fn register_validator(py: Python<'_>, validator: Py<PyAny>) -> PyResult<()>
 ///     def name(self) -> str:
 ///         return "my_validator"
 ///
-///     def validate(self, result: dict) -> None:
+///     def validate(self, result: ExtractionResult) -> None:
 ///         pass
 ///
 /// register_validator(MyValidator())
@@ -433,7 +380,7 @@ pub fn clear_validators(py: Python<'_>) -> PyResult<()> {
 ///     def name(self) -> str:
 ///         return "my_validator"
 ///
-///     def validate(self, result: dict) -> None:
+///     def validate(self, result: ExtractionResult) -> None:
 ///         pass
 ///
 /// # Register validator