kreuzberg 4.0.0.pre.rc.7 → 4.0.0.pre.rc.11

data/vendor/kreuzberg-ffi/kreuzberg.h

@@ -0,0 +1,1087 @@
+/* Auto-generated C bindings for Kreuzberg */
+
+#ifndef KREUZBERG_FFI_H
+#define KREUZBERG_FFI_H
+
+#pragma once
+
+/* Warning, this file is autogenerated by cbindgen. Don't modify this manually. */
+
+#include <stdarg.h>
+#include <stdbool.h>
+#include <stdint.h>
+#include <stdlib.h>
+/**
+ * Opaque type for extraction configuration.
+ * This is an opaque pointer type - callers should not access its internals.
+ */
+typedef struct ExtractionConfig ExtractionConfig;
+
+
+/**
+ * C-compatible extraction result structure
+ *
+ * Must be kept in sync with the Java side's MemoryLayout definition in KreuzbergFFI.java
+ * Field order: 11 pointers (8 bytes each) + 1 bool + 7 bytes padding = 96 bytes total
+ */
+typedef struct CExtractionResult {
+  /**
+   * Extracted text content (null-terminated UTF-8 string, must be freed with kreuzberg_free_string)
+   */
+  char *content;
+  /**
+   * Detected MIME type (null-terminated string, must be freed with kreuzberg_free_string)
+   */
+  char *mime_type;
+  /**
+   * Document language (null-terminated string, or NULL if not available, must be freed with kreuzberg_free_string)
+   */
+  char *language;
+  /**
+   * Document date (null-terminated string, or NULL if not available, must be freed with kreuzberg_free_string)
+   */
+  char *date;
+  /**
+   * Document subject (null-terminated string, or NULL if not available, must be freed with kreuzberg_free_string)
+   */
+  char *subject;
+  /**
+   * Tables as JSON array (null-terminated string, or NULL if no tables, must be freed with kreuzberg_free_string)
+   */
+  char *tables_json;
+  /**
+   * Detected languages as JSON array (null-terminated string, or NULL if not available, must be freed with kreuzberg_free_string)
+   */
+  char *detected_languages_json;
+  /**
+   * Metadata as JSON object (null-terminated string, or NULL if no metadata, must be freed with kreuzberg_free_string)
+   */
+  char *metadata_json;
+  /**
+   * Text chunks as JSON array (null-terminated string, or NULL if not available, must be freed with kreuzberg_free_string)
+   */
+  char *chunks_json;
+  /**
+   * Extracted images as JSON array (null-terminated string, or NULL if not available, must be freed with kreuzberg_free_string)
+   */
+  char *images_json;
+  /**
+   * Page structure as JSON object (null-terminated string, or NULL if not available, must be freed with kreuzberg_free_string)
+   */
+  char *page_structure_json;
+  /**
+   * Whether extraction was successful
+   */
+  bool success;
+  /**
+   * Padding to match Java MemoryLayout (7 bytes padding to align to 8-byte boundary)
+   */
+  uint8_t _padding1[7];
+} CExtractionResult;
+
+/**
+ * C-compatible structure for batch extraction results
+ *
+ * Must be kept in sync with the Java side's MemoryLayout definition in KreuzbergFFI.java
+ * Field order: 1 pointer (8 bytes) + 1 usize (8 bytes) + 1 bool + 7 bytes padding = 24 bytes total
+ */
+typedef struct CBatchResult {
+  /**
+   * Array of extraction results
+   */
+  struct CExtractionResult **results;
+  /**
+   * Number of results
+   */
+  uintptr_t count;
+  /**
+   * Whether batch operation was successful
+   */
+  bool success;
+  /**
+   * Padding to match Java MemoryLayout (7 bytes padding to align to 8-byte boundary)
+   */
+  uint8_t _padding2[7];
+} CBatchResult;
+
+/**
+ * C-compatible structure for passing byte array with MIME type in batch operations
+ *
+ * Must be kept in sync with the Java side's MemoryLayout definition in KreuzbergFFI.java
+ * Field order: 1 pointer (8 bytes) + 1 usize (8 bytes) + 1 pointer (8 bytes) = 24 bytes total
+ */
+typedef struct CBytesWithMime {
+  /**
+   * Pointer to byte data
+   */
+  const uint8_t *data;
+  /**
+   * Length of byte data
+   */
+  uintptr_t data_len;
+  /**
+   * MIME type as null-terminated C string
+   */
+  const char *mime_type;
+} CBytesWithMime;
+
+/**
+ * Type alias for the OCR backend callback function.
+ *
+ * # Parameters
+ *
+ * - `image_bytes`: Pointer to image data
+ * - `image_length`: Length of image data in bytes
+ * - `config_json`: JSON-encoded OcrConfig (null-terminated string)
+ *
+ * # Returns
+ *
+ * Null-terminated string containing extracted text (must be freed by Rust via kreuzberg_free_string),
+ * or NULL on error.
+ *
+ * # Safety
+ *
+ * The callback must:
+ * - Not store the image_bytes pointer (it's only valid for the duration of the call)
+ * - Return a valid null-terminated UTF-8 string allocated by the caller
+ * - Return NULL on error (error message should be retrievable separately)
+ */
+typedef char *(*OcrBackendCallback)(const uint8_t *image_bytes,
+                                    uintptr_t image_length,
+                                    const char *config_json);
+
+/**
+ * Type alias for the PostProcessor callback function.
+ *
+ * # Parameters
+ *
+ * - `result_json`: JSON-encoded ExtractionResult (null-terminated string)
+ *
+ * # Returns
+ *
+ * Null-terminated JSON string containing the processed ExtractionResult
+ * (must be freed by Rust via kreuzberg_free_string), or NULL on error.
+ *
+ * # Safety
+ *
+ * The callback must:
+ * - Not store the result_json pointer (it's only valid for the duration of the call)
+ * - Return a valid null-terminated UTF-8 JSON string allocated by the caller
+ * - Return NULL on error (error message should be retrievable separately)
+ */
+typedef char *(*PostProcessorCallback)(const char *result_json);
+
+/**
+ * Type alias for the DocumentExtractor callback function.
+ *
+ * # Parameters
+ *
+ * - `content`: Raw document bytes
+ * - `content_len`: Length of the content array
+ * - `mime_type`: MIME type of the document (null-terminated string)
+ * - `config_json`: JSON-encoded ExtractionConfig (null-terminated string)
+ *
+ * # Returns
+ *
+ * Null-terminated JSON string containing the ExtractionResult, or NULL on error.
+ * The returned string must be freeable by kreuzberg_free_string.
+ *
+ * # Safety
+ *
+ * The callback must:
+ * - Not store the content, mime_type, or config_json pointers (only valid during the call)
+ * - Return a valid null-terminated UTF-8 JSON string or NULL on error
+ * - The returned string must be freeable by kreuzberg_free_string
+ */
+typedef char *(*DocumentExtractorCallback)(const uint8_t *content,
+                                           uintptr_t content_len,
+                                           const char *mime_type,
+                                           const char *config_json);
+
+/**
+ * Type alias for the Validator callback function.
+ *
+ * # Parameters
+ *
+ * - `result_json`: JSON-encoded ExtractionResult (null-terminated string)
+ *
+ * # Returns
+ *
+ * Null-terminated error message string if validation fails (must be freed by Rust
+ * via kreuzberg_free_string), or NULL if validation passes.
+ *
+ * # Safety
+ *
+ * The callback must:
+ * - Not store the result_json pointer (it's only valid for the duration of the call)
+ * - Return a valid null-terminated UTF-8 string (error message) if validation fails
+ * - Return NULL if validation passes
+ * - The returned string must be freeable by kreuzberg_free_string
+ */
+typedef char *(*ValidatorCallback)(const char *result_json);
+
+/**
+ * Extract text and metadata from a file (synchronous).
+ *
+ * # Safety
+ *
+ * - `file_path` must be a valid null-terminated C string
+ * - The returned pointer must be freed with `kreuzberg_free_result`
+ * - Returns NULL on error (check `kreuzberg_last_error` for details)
+ *
+ * # Example (C)
+ *
+ * ```c
+ * const char* path = "/path/to/document.pdf";
+ * CExtractionResult* result = kreuzberg_extract_file_sync(path);
+ * if (result != NULL && result->success) {
+ *     printf("Content: %s\n", result->content);
+ *     printf("MIME: %s\n", result->mime_type);
+ *     kreuzberg_free_result(result);
+ * } else {
+ *     const char* error = kreuzberg_last_error();
+ *     printf("Error: %s\n", error);
+ * }
+ * ```
+ */
+struct CExtractionResult *kreuzberg_extract_file_sync(const char *file_path);
+
+/**
+ * Detect MIME type from a file path.
+ *
+ * # Safety
+ *
+ * - `file_path` must be a valid null-terminated C string
+ * - The returned string must be freed with `kreuzberg_free_string`
+ * - Returns NULL on error (check `kreuzberg_last_error`)
+ */
+char *kreuzberg_detect_mime_type(const char *file_path, bool check_exists);
+
+/**
+ * Validate that a MIME type is supported by Kreuzberg.
+ *
+ * # Safety
+ *
+ * - `mime_type` must be a valid null-terminated C string
+ * - The returned string must be freed with `kreuzberg_free_string`
+ * - Returns NULL on error (check `kreuzberg_last_error`)
+ */
+char *kreuzberg_validate_mime_type(const char *mime_type);
+
+/**
+ * List available embedding preset names.
+ *
+ * # Safety
+ *
+ * - Returned string is a JSON array and must be freed with `kreuzberg_free_string`
+ * - Returns NULL on error (check `kreuzberg_last_error`)
+ */
+char *kreuzberg_list_embedding_presets(void);
+
+/**
+ * Get a specific embedding preset by name.
+ *
+ * # Safety
+ *
+ * - `name` must be a valid null-terminated C string
+ * - Returned string is JSON object and must be freed with `kreuzberg_free_string`
+ * - Returns NULL on error (check `kreuzberg_last_error`)
+ */
+char *kreuzberg_get_embedding_preset(const char *name);
+
+/**
+ * Extract text and metadata from a file with custom configuration (synchronous).
+ *
+ * # Safety
+ *
+ * - `file_path` must be a valid null-terminated C string
+ * - `config_json` must be a valid null-terminated C string containing JSON, or NULL for default config
+ * - The returned pointer must be freed with `kreuzberg_free_result`
+ * - Returns NULL on error (check `kreuzberg_last_error` for details)
+ *
+ * # Example (C)
+ *
+ * ```c
+ * const char* path = "/path/to/document.pdf";
+ * const char* config = "{\"force_ocr\": true, \"ocr\": {\"language\": \"deu\"}}";
+ * CExtractionResult* result = kreuzberg_extract_file_sync_with_config(path, config);
+ * if (result != NULL && result->success) {
+ *     printf("Content: %s\n", result->content);
+ *     kreuzberg_free_result(result);
+ * }
+ * ```
+ */
+struct CExtractionResult *kreuzberg_extract_file_sync_with_config(const char *file_path,
+                                                                  const char *config_json);
+
+/**
+ * Extract text and metadata from byte array (synchronous).
+ *
+ * # Safety
+ *
+ * - `data` must be a valid pointer to a byte array of length `data_len`
+ * - `mime_type` must be a valid null-terminated C string
+ * - The returned pointer must be freed with `kreuzberg_free_result`
+ * - Returns NULL on error (check `kreuzberg_last_error` for details)
+ *
+ * # Example (C)
+ *
+ * ```c
+ * const uint8_t* data = ...; // Document bytes
+ * size_t len = ...;           // Length of data
+ * const char* mime = "application/pdf";
+ * CExtractionResult* result = kreuzberg_extract_bytes_sync(data, len, mime);
+ * if (result != NULL && result->success) {
+ *     printf("Content: %s\n", result->content);
+ *     kreuzberg_free_result(result);
+ * } else {
+ *     const char* error = kreuzberg_last_error();
+ *     printf("Error: %s\n", error);
+ * }
+ * ```
+ */
+struct CExtractionResult *kreuzberg_extract_bytes_sync(const uint8_t *data,
+                                                       uintptr_t data_len,
+                                                       const char *mime_type);
+
+/**
+ * Extract text and metadata from byte array with custom configuration (synchronous).
+ *
+ * # Safety
+ *
+ * - `data` must be a valid pointer to a byte array of length `data_len`
+ * - `mime_type` must be a valid null-terminated C string
+ * - `config_json` must be a valid null-terminated C string containing JSON, or NULL for default config
+ * - The returned pointer must be freed with `kreuzberg_free_result`
+ * - Returns NULL on error (check `kreuzberg_last_error` for details)
+ *
+ * # Example (C)
+ *
+ * ```c
+ * const uint8_t* data = ...; // Document bytes
+ * size_t len = ...;           // Length of data
+ * const char* mime = "application/pdf";
+ * const char* config = "{\"force_ocr\": true, \"ocr\": {\"language\": \"deu\"}}";
+ * CExtractionResult* result = kreuzberg_extract_bytes_sync_with_config(data, len, mime, config);
+ * if (result != NULL && result->success) {
+ *     printf("Content: %s\n", result->content);
+ *     kreuzberg_free_result(result);
+ * }
+ * ```
+ */
+struct CExtractionResult *kreuzberg_extract_bytes_sync_with_config(const uint8_t *data,
+                                                                   uintptr_t data_len,
+                                                                   const char *mime_type,
+                                                                   const char *config_json);
+
+/**
+ * Batch extract text and metadata from multiple files (synchronous).
+ *
+ * # Safety
+ *
+ * - `file_paths` must be a valid pointer to an array of null-terminated C strings
+ * - `count` must be the number of file paths in the array
+ * - `config_json` must be a valid null-terminated C string containing JSON, or NULL for default config
+ * - The returned pointer must be freed with `kreuzberg_free_batch_result`
+ * - Returns NULL on error (check `kreuzberg_last_error` for details)
+ */
+struct CBatchResult *kreuzberg_batch_extract_files_sync(const char *const *file_paths,
+                                                        uintptr_t count,
+                                                        const char *config_json);
+
+/**
+ * Batch extract text and metadata from multiple byte arrays (synchronous).
+ *
+ * # Safety
+ *
+ * - `items` must be a valid pointer to an array of CBytesWithMime structures
+ * - `count` must be the number of items in the array
+ * - `config_json` must be a valid null-terminated C string containing JSON, or NULL for default config
+ * - The returned pointer must be freed with `kreuzberg_free_batch_result`
+ * - Returns NULL on error (check `kreuzberg_last_error` for details)
+ */
+struct CBatchResult *kreuzberg_batch_extract_bytes_sync(const struct CBytesWithMime *items,
+                                                        uintptr_t count,
+                                                        const char *config_json);
+
+/**
+ * Load an extraction configuration from a TOML/YAML/JSON file.
+ *
+ * # Safety
+ *
+ * - `file_path` must be a valid null-terminated C string
+ * - The returned string must be freed with `kreuzberg_free_string`
+ * - Returns NULL on error (check `kreuzberg_last_error`)
+ */
+char *kreuzberg_load_extraction_config_from_file(const char *file_path);
+
+/**
+ * Free a batch result returned by batch extraction functions.
+ *
+ * # Safety
+ *
+ * - `batch_result` must be a pointer previously returned by a batch extraction function
+ * - `batch_result` can be NULL (no-op)
+ * - `batch_result` must not be used after this call
+ * - All results and strings within the batch result will be freed automatically
+ */
+void kreuzberg_free_batch_result(struct CBatchResult *batch_result);
+
+/**
+ * Free a string returned by Kreuzberg functions.
+ *
+ * # Safety
+ *
+ * - `s` must be a string previously returned by a Kreuzberg function
+ * - `s` can be NULL (no-op)
+ * - `s` must not be used after this call
+ *
+ * # Example (C)
+ *
+ * ```c
+ * char* str = result->content;
+ * kreuzberg_free_string(str);
+ * // str is now invalid
+ * ```
+ */
+void kreuzberg_free_string(char *s);
+
+/**
+ * Clone a null-terminated string using Rust's allocator.
+ *
+ * # Safety
+ *
+ * - `s` must be a valid null-terminated UTF-8 string
+ * - Returned pointer must be freed with `kreuzberg_free_string`
+ * - Returns NULL on error (check `kreuzberg_last_error`)
+ */
+char *kreuzberg_clone_string(const char *s);
+
+/**
+ * Free an extraction result returned by `kreuzberg_extract_file_sync`.
+ *
+ * # Safety
+ *
+ * - `result` must be a pointer previously returned by `kreuzberg_extract_file_sync`
+ * - `result` can be NULL (no-op)
+ * - `result` must not be used after this call
+ * - All string fields within the result will be freed automatically
+ *
+ * # Example (C)
+ *
+ * ```c
+ * CExtractionResult* result = kreuzberg_extract_file_sync(path);
+ * // Use result...
+ * kreuzberg_free_result(result);
+ * // result is now invalid
+ * ```
+ */
+void kreuzberg_free_result(struct CExtractionResult *result);
+
+/**
+ * Get the last error message from a failed operation.
+ *
+ * # Safety
+ *
+ * - Returns a static string that does not need to be freed
+ * - Returns NULL if no error has occurred
+ * - The returned string is valid until the next Kreuzberg function call on the same thread
+ *
+ * # Example (C)
+ *
+ * ```c
+ * CExtractionResult* result = kreuzberg_extract_file_sync(path);
+ * if (result == NULL) {
+ *     const char* error = kreuzberg_last_error();
+ *     if (error != NULL) {
+ *         printf("Error: %s\n", error);
+ *     }
+ * }
+ * ```
+ */
+const char *kreuzberg_last_error(void);
+
+/**
+ * Get the error code for the last error.
+ *
+ * Returns the error code as an i32. Error codes are defined in ErrorCode enum:
+ * - 0: Success (no error)
+ * - 1: GenericError
+ * - 2: Panic
+ * - 3: InvalidArgument
+ * - 4: IoError
+ * - 5: ParsingError
+ * - 6: OcrError
+ * - 7: MissingDependency
+ *
+ * # Safety
+ *
+ * This function is thread-safe and always safe to call.
+ *
+ * # Example (C)
+ *
+ * ```c
+ * CExtractionResult* result = kreuzberg_extract_file_sync(path);
+ * if (result == NULL) {
+ *     int32_t code = kreuzberg_last_error_code();
+ *     if (code == 2) {
+ *         // A panic occurred
+ *     }
+ * }
+ * ```
+ */
+int32_t kreuzberg_last_error_code(void);
+
+/**
+ * Get the panic context for the last error (if it was a panic).
+ *
+ * Returns a JSON string containing panic context information, or NULL if
+ * the last error was not a panic.
+ *
+ * The JSON structure contains:
+ * - file: Source file where panic occurred
+ * - line: Line number
+ * - function: Function name
+ * - message: Panic message
+ * - timestamp_secs: Unix timestamp (seconds since epoch)
+ *
+ * # Safety
+ *
+ * The returned string must be freed with kreuzberg_free_string().
+ *
+ * # Example (C)
+ *
+ * ```c
+ * CExtractionResult* result = kreuzberg_extract_file_sync(path);
+ * if (result == NULL && kreuzberg_last_error_code() == 2) {
+ *     const char* context = kreuzberg_last_panic_context();
+ *     if (context != NULL) {
+ *         printf("Panic context: %s\n", context);
+ *         kreuzberg_free_string((char*)context);
+ *     }
+ * }
+ * ```
+ */
+char *kreuzberg_last_panic_context(void);
+
+/**
+ * Get the library version string.
+ *
+ * # Safety
+ *
+ * - Returns a static string that does not need to be freed
+ * - The returned string is always valid
+ *
+ * # Example (C)
+ *
+ * ```c
+ * const char* version = kreuzberg_version();
+ * printf("Kreuzberg version: %s\n", version);
+ * ```
+ */
+const char *kreuzberg_version(void);
+
+/**
+ * Register a custom OCR backend via FFI callback.
+ *
+ * # Safety
+ *
+ * - `name` must be a valid null-terminated C string
+ * - `callback` must be a valid function pointer that:
+ *   - Does not store the image_bytes pointer
+ *   - Returns a null-terminated UTF-8 string or NULL on error
+ *   - The returned string must be freeable by kreuzberg_free_string
+ * - Returns true on success, false on error (check kreuzberg_last_error)
+ *
+ * # Example (C)
+ *
+ * ```c
+ * char* my_ocr_backend(const uint8_t* image_bytes, size_t image_length, const char* config_json) {
+ *     // Implement OCR logic here
+ *     // Return allocated string with result, or NULL on error
+ *     return strdup("Extracted text");
+ * }
+ *
+ * bool success = kreuzberg_register_ocr_backend("my-ocr", my_ocr_backend);
+ * if (!success) {
+ *     const char* error = kreuzberg_last_error();
+ *     printf("Failed to register: %s\n", error);
+ * }
+ * ```
+ */
+bool kreuzberg_register_ocr_backend(const char *name, OcrBackendCallback callback);
+
+/**
+ * Register a custom OCR backend with explicit language support via FFI callback.
+ *
+ * # Safety
+ *
+ * - `languages_json` must be a null-terminated JSON array of language codes or NULL
+ * - See `kreuzberg_register_ocr_backend` for additional safety notes.
+ */
+bool kreuzberg_register_ocr_backend_with_languages(const char *name,
+                                                   OcrBackendCallback callback,
+                                                   const char *languages_json);
+
+/**
+ * Register a custom PostProcessor via FFI callback.
+ *
+ * # Safety
+ *
+ * - `name` must be a valid null-terminated C string
+ * - `callback` must be a valid function pointer that:
+ *   - Does not store the result_json pointer
+ *   - Returns a null-terminated UTF-8 JSON string or NULL on error
+ *   - The returned string must be freeable by kreuzberg_free_string
+ * - `priority` determines the order of execution (higher priority runs first)
+ * - Returns true on success, false on error (check kreuzberg_last_error)
+ *
+ * # Example (C)
+ *
+ * ```c
+ * char* my_post_processor(const char* result_json) {
+ *     // Parse result_json, modify it, return JSON string
+ *     return strdup("{\"content\":\"PROCESSED\"}");
+ * }
+ *
+ * bool success = kreuzberg_register_post_processor("my-processor", my_post_processor, 100);
+ * if (!success) {
+ *     const char* error = kreuzberg_last_error();
+ *     printf("Failed to register: %s\n", error);
+ * }
+ * ```
+ */
+bool kreuzberg_register_post_processor(const char *name,
+                                       PostProcessorCallback callback,
+                                       int32_t priority);
+
+/**
+ * Register a custom PostProcessor with an explicit processing stage.
+ *
+ * # Safety
+ *
+ * - `name` must be a valid null-terminated C string
+ * - `stage` must be a valid null-terminated C string containing "early", "middle", or "late"
+ * - `callback` must be a valid function pointer that:
+ *   - Does not store the result_json pointer
+ *   - Returns a null-terminated UTF-8 JSON string or NULL on error
+ *   - The returned string must be freeable by kreuzberg_free_string
+ * - `priority` determines the order of execution within the stage (higher priority runs first)
+ * - Returns true on success, false on error (check kreuzberg_last_error)
+ */
+bool kreuzberg_register_post_processor_with_stage(const char *name,
+                                                  PostProcessorCallback callback,
+                                                  int32_t priority,
+                                                  const char *stage);
+
+/**
+ * Unregister a PostProcessor by name.
+ *
+ * # Safety
+ *
+ * - `name` must be a valid null-terminated C string
+ * - Returns true on success, false on error (check kreuzberg_last_error)
+ *
+ * # Example (C)
+ *
+ * ```c
+ * bool success = kreuzberg_unregister_post_processor("my-processor");
+ * if (!success) {
+ *     const char* error = kreuzberg_last_error();
+ *     printf("Failed to unregister: %s\n", error);
+ * }
+ * ```
+ */
+bool kreuzberg_unregister_post_processor(const char *name);
+
+/**
+ * Clear all registered PostProcessors.
+ *
+ * # Safety
+ *
+ * - Removes all registered processors. Subsequent extractions will run without them.
+ * - Returns true on success, false on error.
+ */
+bool kreuzberg_clear_post_processors(void);
+
+/**
+ * List all registered PostProcessors as a JSON array of names.
+ *
+ * # Safety
+ *
+ * - Returned string must be freed with `kreuzberg_free_string`.
+ * - Returns NULL on error (check `kreuzberg_last_error`).
+ */
+char *kreuzberg_list_post_processors(void);
+
+/**
+ * Register a custom DocumentExtractor via FFI callback.
+ *
+ * # Safety
+ *
+ * - `name` must be a valid null-terminated C string
+ * - `callback` must be a valid function pointer that:
+ *   - Does not store the content, mime_type, or config_json pointers
+ *   - Returns a null-terminated UTF-8 JSON string or NULL on error
+ *   - The returned string must be freeable by kreuzberg_free_string
+ * - `mime_types` must be a valid null-terminated C string containing comma-separated MIME types
+ * - `priority` determines the order of selection (higher priority preferred)
+ * - Returns true on success, false on error (check kreuzberg_last_error)
+ *
+ * # Example (C)
+ *
+ * ```c
+ * char* my_extractor(const uint8_t* content, size_t len, const char* mime_type, const char* config) {
+ *     // Extract content from bytes, return JSON ExtractionResult
+ *     return strdup("{\"content\":\"extracted text\",\"mime_type\":\"text/plain\",\"metadata\":{}}");
+ * }
+ *
+ * bool success = kreuzberg_register_document_extractor(
+ *     "my-extractor",
+ *     my_extractor,
+ *     "application/x-custom,text/x-custom",
+ *     100
+ * );
+ * if (!success) {
+ *     const char* error = kreuzberg_last_error();
+ *     printf("Failed to register: %s\n", error);
+ * }
+ * ```
+ */
+bool kreuzberg_register_document_extractor(const char *name,
+                                           DocumentExtractorCallback callback,
+                                           const char *mime_types,
+                                           int32_t priority);
+
+/**
+ * Unregister a DocumentExtractor by name.
+ *
+ * # Safety
+ *
+ * - `name` must be a valid null-terminated C string
+ * - Returns true on success, false on error (check kreuzberg_last_error)
+ *
+ * # Example (C)
+ *
+ * ```c
+ * bool success = kreuzberg_unregister_document_extractor("my-extractor");
+ * if (!success) {
+ *     const char* error = kreuzberg_last_error();
+ *     printf("Failed to unregister: %s\n", error);
+ * }
+ * ```
+ */
+bool kreuzberg_unregister_document_extractor(const char *name);
+
+/**
+ * List all registered DocumentExtractors as a JSON array of names.
+ *
+ * # Safety
+ *
+ * - Returned string must be freed with `kreuzberg_free_string`.
+ * - Returns NULL on error (check `kreuzberg_last_error`).
+ */
+char *kreuzberg_list_document_extractors(void);
+
+/**
+ * Register a custom Validator via FFI callback.
+ *
+ * # Safety
+ *
+ * - `name` must be a valid null-terminated C string
+ * - `callback` must be a valid function pointer that:
+ *   - Does not store the result_json pointer
+ *   - Returns a null-terminated UTF-8 string (error message) if validation fails
+ *   - Returns NULL if validation passes
+ *   - The returned string must be freeable by kreuzberg_free_string
+ * - `priority` determines the order of validation (higher priority runs first)
+ * - Returns true on success, false on error (check kreuzberg_last_error)
+ *
+ * # Example (C)
+ *
+ * ```c
+ * char* my_validator(const char* result_json) {
+ *     // Parse result_json, validate it
+ *     // Return error message if validation fails, NULL if passes
+ *     if (invalid) {
+ *         return strdup("Validation failed: content too short");
+ *     }
+ *     return NULL;
+ * }
+ *
+ * bool success = kreuzberg_register_validator("my-validator", my_validator, 100);
+ * if (!success) {
+ *     const char* error = kreuzberg_last_error();
+ *     printf("Failed to register: %s\n", error);
+ * }
+ * ```
+ */
+bool kreuzberg_register_validator(const char *name, ValidatorCallback callback, int32_t priority);
+
+/**
+ * Unregister a Validator by name.
+ *
+ * # Safety
+ *
+ * - `name` must be a valid null-terminated C string
+ * - Returns true on success, false on error (check kreuzberg_last_error)
+ *
+ * # Example (C)
+ *
+ * ```c
+ * bool success = kreuzberg_unregister_validator("my-validator");
+ * if (!success) {
+ *     const char* error = kreuzberg_last_error();
+ *     printf("Failed to unregister: %s\n", error);
+ * }
+ * ```
+ */
+bool kreuzberg_unregister_validator(const char *name);
+
+/**
+ * Clear all registered Validators.
+ *
+ * # Safety
+ *
+ * - Removes all validators. Subsequent extractions will skip custom validation.
+ * - Returns true on success, false on error.
+ */
+bool kreuzberg_clear_validators(void);
+
+/**
+ * List all registered Validators as a JSON array of names.
+ *
+ * # Safety
+ *
+ * - Returned string must be freed with `kreuzberg_free_string`.
+ * - Returns NULL on error (check `kreuzberg_last_error`).
+ */
+char *kreuzberg_list_validators(void);
+
+/**
+ * Unregister an OCR backend by name.
+ *
+ * # Safety
+ *
+ * - `name` must be a valid null-terminated C string
+ * - Returns true on success, false on error (check kreuzberg_last_error)
+ *
+ * # Example (C)
+ *
+ * ```c
+ * bool success = kreuzberg_unregister_ocr_backend("custom-ocr");
+ * if (!success) {
+ *     const char* error = kreuzberg_last_error();
+ *     printf("Failed to unregister: %s\n", error);
+ * }
+ * ```
+ */
+bool kreuzberg_unregister_ocr_backend(const char *name);
+
+/**
+ * List all registered OCR backends as a JSON array of names.
+ *
+ * # Safety
+ *
+ * - Returned string must be freed with `kreuzberg_free_string`.
+ * - Returns NULL on error (check `kreuzberg_last_error`).
+ *
+ * # Example (C)
+ *
+ * ```c
+ * char* backends = kreuzberg_list_ocr_backends();
+ * if (backends == NULL) {
+ *     const char* error = kreuzberg_last_error();
+ *     printf("Failed to list backends: %s\n", error);
+ * } else {
+ *     printf("OCR backends: %s\n", backends);
+ *     kreuzberg_free_string(backends);
+ * }
+ * ```
+ */
+char *kreuzberg_list_ocr_backends(void);
+
+/**
+ * Clear all registered OCR backends.
+ *
+ * # Safety
+ *
+ * - Removes all registered OCR backends. Subsequent extractions will use only built-in backends.
+ * - Returns true on success, false on error.
+ *
+ * # Example (C)
+ *
+ * ```c
+ * bool success = kreuzberg_clear_ocr_backends();
+ * if (!success) {
+ *     const char* error = kreuzberg_last_error();
+ *     printf("Failed to clear OCR backends: %s\n", error);
+ * }
+ * ```
+ */
+bool kreuzberg_clear_ocr_backends(void);
+
+/**
+ * Clear all registered DocumentExtractors.
+ *
+ * # Safety
+ *
+ * - Removes all registered extractors. Subsequent extractions will use only built-in extractors.
+ * - Returns true on success, false on error.
+ *
+ * # Example (C)
+ *
+ * ```c
+ * bool success = kreuzberg_clear_document_extractors();
+ * if (!success) {
+ *     const char* error = kreuzberg_last_error();
+ *     printf("Failed to clear document extractors: %s\n", error);
+ * }
+ * ```
+ */
+bool kreuzberg_clear_document_extractors(void);
+
+/**
+ * Detect MIME type from raw bytes.
+ *
+ * # Safety
+ *
+ * - `bytes` must be a valid pointer to byte data
+ * - `len` must be the correct length of the byte array
+ * - The returned string must be freed with `kreuzberg_free_string`
+ * - Returns NULL on error (check `kreuzberg_last_error`)
+ *
+ * # Example (C)
+ *
+ * ```c
+ * const char* pdf_bytes = "%PDF-1.4\n";
+ * char* mime = kreuzberg_detect_mime_type_from_bytes((const uint8_t*)pdf_bytes, strlen(pdf_bytes));
+ * if (mime == NULL) {
+ *     const char* error = kreuzberg_last_error();
+ *     printf("Failed to detect MIME type: %s\n", error);
+ * } else {
+ *     printf("MIME type: %s\n", mime);
+ *     kreuzberg_free_string(mime);
+ * }
+ * ```
+ */
+char *kreuzberg_detect_mime_type_from_bytes(const uint8_t *bytes, uintptr_t len);
+
+/**
+ * Detect MIME type from file path (checks extension and reads file content).
+ *
+ * # Safety
+ *
+ * - `file_path` must be a valid null-terminated C string
+ * - The returned string must be freed with `kreuzberg_free_string`
+ * - Returns NULL on error (check `kreuzberg_last_error`)
+ *
+ * # Example (C)
+ *
+ * ```c
+ * char* mime = kreuzberg_detect_mime_type_from_path("document.pdf");
+ * if (mime == NULL) {
+ *     const char* error = kreuzberg_last_error();
+ *     printf("Failed to detect MIME type: %s\n", error);
+ * } else {
+ *     printf("MIME type: %s\n", mime);
+ *     kreuzberg_free_string(mime);
+ * }
+ * ```
+ */
+char *kreuzberg_detect_mime_type_from_path(const char *file_path);
+
+/**
+ * Get file extensions for a MIME type.
+ *
+ * # Safety
+ *
+ * - `mime_type` must be a valid null-terminated C string
+ * - The returned string is a JSON array of extensions (must be freed with `kreuzberg_free_string`)
+ * - Returns NULL on error (check `kreuzberg_last_error`)
+ *
+ * # Example (C)
+ *
+ * ```c
+ * char* extensions = kreuzberg_get_extensions_for_mime("application/pdf");
+ * if (extensions == NULL) {
+ *     const char* error = kreuzberg_last_error();
+ *     printf("Failed to get extensions: %s\n", error);
+ * } else {
+ *     printf("Extensions: %s\n", extensions);
+ *     kreuzberg_free_string(extensions);
+ * }
+ * ```
+ */
+char *kreuzberg_get_extensions_for_mime(const char *mime_type);
+
+/**
+ * Load an ExtractionConfig from a file.
+ *
+ * Automatically detects the file format based on extension:
+ * - `.toml` - TOML format
+ * - `.yaml`, `.yml` - YAML format
+ * - `.json` - JSON format
+ *
+ * # Safety
+ *
+ * - `path` must be a valid null-terminated C string representing a file path
+ * - Returns a pointer to ExtractionConfig on success, NULL on error
+ * - The returned config must be freed with `kreuzberg_free_config`
+ * - Check `kreuzberg_last_error` on NULL return
+ *
+ * # Example (C)
+ *
+ * ```c
+ * ExtractionConfig* config = kreuzberg_config_from_file("kreuzberg.toml");
+ * if (config == NULL) {
+ *     const char* error = kreuzberg_last_error();
+ *     printf("Failed to load config: %s\n", error);
+ *     return 1;
+ * }
+ *
+ * // Use config...
+ * char* result = kreuzberg_extract_file_with_config_sync("document.pdf", config);
+ *
+ * kreuzberg_free_config(config);
+ * ```
+ */
+ExtractionConfig *kreuzberg_config_from_file(const char *path);
+
+/**
+ * Discover and load an ExtractionConfig by searching parent directories.
+ *
+ * Searches the current directory and all parent directories for:
+ * - `kreuzberg.toml`
+ * - `kreuzberg.yaml`
+ * - `kreuzberg.yml`
+ * - `kreuzberg.json`
+ *
+ * Returns the first config file found as JSON, or NULL if none found.
+ *
+ * # Safety
+ *
+ * - The returned string must be freed with `kreuzberg_free_string`
+ * - Returns NULL if no config found or on error (check `kreuzberg_last_error`)
+ *
+ * # Example (C)
+ *
+ * ```c
+ * char* config_json = kreuzberg_config_discover();
+ * if (config_json == NULL) {
+ *     const char* error = kreuzberg_last_error();
+ *     if (error != NULL && strlen(error) > 0) {
+ *         printf("Error discovering config: %s\n", error);
+ *         return 1;
+ *     }
+ *     // No config found, use defaults
+ *     printf("No config file found\n");
+ * } else {
+ *     printf("Config: %s\n", config_json);
+ *     kreuzberg_free_string(config_json);
+ * }
+ * ```
+ */
+char *kreuzberg_config_discover(void);
+
+#endif  /* KREUZBERG_FFI_H */