kreuzberg 4.0.8 → 4.1.0

data/vendor/kreuzberg-ffi/kreuzberg.h

@@ -25,6 +25,14 @@ typedef struct ExtractionConfig ExtractionConfig;
 typedef struct ExtractionResult ExtractionResult;
 
 
+/**
+ * Opaque builder struct for constructing ExtractionConfig.
+ *
+ * Use kreuzberg_config_builder_new() to create, set fields with setters,
+ * then finalize with kreuzberg_config_builder_build().
+ */
+typedef struct ConfigBuilder ConfigBuilder;
+
 typedef struct Option_ErrorCallback Option_ErrorCallback;
 
 /**
@@ -658,22 +666,6 @@ int kreuzberg_extract_batch_parallel(const char *const *files,
  * - `json_config` must be a valid null-terminated C string
  * - The returned pointer must be freed with `kreuzberg_config_free`
  * - Returns NULL if parsing fails (error available via `kreuzberg_last_error`)
- *
- * # Example (C)
- *
- * ```c
- * const char* config_json = "{\"use_cache\": true, \"ocr\": {\"backend\": \"tesseract\"}}";
- * ExtractionConfig* config = kreuzberg_config_from_json(config_json);
- * if (config == NULL) {
- *     printf("Error: %s\n", kreuzberg_last_error());
- *     return 1;
- * }
- *
- * // Use config...
- * // char* result = kreuzberg_extract_file_with_config("doc.pdf", config);
- *
- * kreuzberg_config_free(config);
- * ```
  */
 ExtractionConfig *kreuzberg_config_from_json(const char *json_config);
 
@@ -685,30 +677,12 @@ ExtractionConfig *kreuzberg_config_from_json(const char *json_config);
  * - `config` must be a pointer previously returned by a config creation function
  * - `config` can be NULL (no-op)
  * - `config` must not be used after this call
- *
- * # Example (C)
- *
- * ```c
- * ExtractionConfig* config = kreuzberg_config_from_json("{...}");
- * if (config != NULL) {
- *     // Use config...
- *     kreuzberg_config_free(config);
- * }
- * ```
  */
 void kreuzberg_config_free(ExtractionConfig *config);
 
 /**
  * Validate a JSON config string without parsing it.
  *
- * This function checks if a JSON config string is valid and would parse correctly,
- * without allocating the full ExtractionConfig structure. Useful for validation
- * before committing to parsing.
- *
- * # Arguments
- *
- * * `json_config` - Null-terminated C string containing JSON configuration
- *
  * # Returns
  *
  * - 1 if valid (would parse successfully)
@@ -717,238 +691,312 @@ void kreuzberg_config_free(ExtractionConfig *config);
  * # Safety
  *
  * - `json_config` must be a valid null-terminated C string
- *
- * # Example (C)
- *
- * ```c
- * const char* config_json = "{\"use_cache\": true}";
- * if (kreuzberg_config_is_valid(config_json)) {
- *     ExtractionConfig* config = kreuzberg_config_from_json(config_json);
- *     // Use config...
- *     kreuzberg_config_free(config);
- * } else {
- *     printf("Invalid config: %s\n", kreuzberg_last_error());
- * }
- * ```
  */
 int32_t kreuzberg_config_is_valid(const char *json_config);
 
 /**
  * Serialize an ExtractionConfig to JSON string.
  *
- * Converts an ExtractionConfig structure to its JSON representation, allowing
- * bindings to serialize configs without reimplementing serialization logic.
+ * # Safety
  *
- * # Arguments
+ * - `config` must be a valid pointer to an ExtractionConfig
+ * - The returned pointer must be freed with `kreuzberg_free_string`
+ */
+char *kreuzberg_config_to_json(const ExtractionConfig *config);
+
+/**
+ * Get a specific field from config as JSON string.
  *
- * * `config` - Pointer to an ExtractionConfig structure
+ * # Safety
+ *
+ * - `config` must be a valid pointer to an ExtractionConfig
+ * - `field_name` must be a valid null-terminated C string
+ */
+char *kreuzberg_config_get_field(const ExtractionConfig *config, const char *field_name);
+
+/**
+ * Merge two configs (override takes precedence over base).
  *
  * # Returns
  *
- * A pointer to a C string containing JSON that MUST be freed with `kreuzberg_free_string`.
- * Returns NULL on error (check `kreuzberg_last_error`).
+ * - 1 on success
+ * - 0 on error (check `kreuzberg_last_error`)
  *
  * # Safety
  *
- * - `config` must be a valid pointer to an ExtractionConfig
- * - `config` cannot be NULL
- * - The returned pointer must be freed with `kreuzberg_free_string`
+ * - `base` must be a valid mutable pointer to an ExtractionConfig
+ * - `override_config` must be a valid pointer to an ExtractionConfig
+ */
+int32_t kreuzberg_config_merge(ExtractionConfig *base, const ExtractionConfig *override_config);
+
+/**
+ * Load an ExtractionConfig from a file (returns JSON string).
  *
- * # Example (C)
+ * # Safety
  *
- * ```c
- * ExtractionConfig* config = kreuzberg_config_from_json("{\"use_cache\": true}");
- * if (config != NULL) {
- *     char* json = kreuzberg_config_to_json(config);
- *     if (json != NULL) {
- *         printf("Serialized: %s\n", json);
- *         kreuzberg_free_string(json);
- *     }
- *     kreuzberg_config_free(config);
- * }
- * ```
+ * - `file_path` must be a valid null-terminated C string
+ * - The returned string must be freed with `kreuzberg_free_string`
  */
-char *kreuzberg_config_to_json(const ExtractionConfig *config);
+char *kreuzberg_load_extraction_config_from_file(const char *file_path);
 
 /**
- * Get a specific field from config as JSON string.
+ * Load an ExtractionConfig from a file (returns pointer to config struct).
  *
- * Retrieves a nested field from the configuration by path and returns its JSON
- * representation. Supports dot notation for nested fields (e.g., "ocr.backend").
+ * # Safety
  *
- * # Arguments
+ * - `path` must be a valid null-terminated C string
+ * - The returned pointer must be freed with `kreuzberg_config_free`
+ */
+ExtractionConfig *kreuzberg_config_from_file(const char *path);
+
+/**
+ * Discover and load an ExtractionConfig by searching parent directories.
  *
- * * `config` - Pointer to an ExtractionConfig structure
- * * `field_name` - Null-terminated C string with field path (e.g., "use_cache", "ocr.backend")
+ * # Safety
  *
- * # Returns
+ * - The returned string must be freed with `kreuzberg_free_string`
+ */
+char *kreuzberg_config_discover(void);
+
+/**
+ * List available embedding preset names.
  *
- * A pointer to a C string containing the field value as JSON, or NULL if:
- * - The field doesn't exist
- * - An error occurs during serialization
+ * # Safety
  *
- * The returned pointer (if non-NULL) must be freed with `kreuzberg_free_string`.
+ * - Returned string is a JSON array and must be freed with `kreuzberg_free_string`
+ */
+char *kreuzberg_list_embedding_presets(void);
+
+/**
+ * Get a specific embedding preset by name.
  *
  * # Safety
  *
- * - `config` must be a valid pointer to an ExtractionConfig
- * - `field_name` must be a valid null-terminated C string
- * - Neither parameter can be NULL
+ * - `name` must be a valid null-terminated C string
+ * - Returned string is JSON object and must be freed with `kreuzberg_free_string`
+ */
+char *kreuzberg_get_embedding_preset(const char *name);
+
+/**
+ * Create a new config builder.
  *
- * # Example (C)
+ * Returns an opaque pointer to ConfigBuilder. Must be freed with
+ * kreuzberg_config_builder_free() or consumed by kreuzberg_config_builder_build().
  *
- * ```c
- * ExtractionConfig* config = kreuzberg_config_from_json(
- *     "{\"use_cache\": true, \"ocr\": {\"backend\": \"tesseract\"}}"
- * );
- * if (config != NULL) {
- *     char* use_cache = kreuzberg_config_get_field(config, "use_cache");
- *     char* backend = kreuzberg_config_get_field(config, "ocr.backend");
+ * # Safety
  *
- *     if (use_cache != NULL) {
- *         printf("use_cache: %s\n", use_cache);
- *         kreuzberg_free_string(use_cache);
- *     }
+ * The returned pointer must be freed with kreuzberg_config_builder_free()
+ * or passed to kreuzberg_config_builder_build().
  *
- *     if (backend != NULL) {
- *         printf("backend: %s\n", backend);
- *         kreuzberg_free_string(backend);
- *     }
+ * # Example (C)
  *
- *     kreuzberg_config_free(config);
- * }
+ * ```c
+ * ConfigBuilder* builder = kreuzberg_config_builder_new();
+ * kreuzberg_config_builder_set_use_cache(builder, 1);
+ * ExtractionConfig* config = kreuzberg_config_builder_build(builder);
+ * // builder is now consumed, don't call kreuzberg_config_builder_free
+ * kreuzberg_config_free(config);
  * ```
  */
-char *kreuzberg_config_get_field(const ExtractionConfig *config, const char *field_name);
+struct ConfigBuilder *kreuzberg_config_builder_new(void);
 
 /**
- * Merge two configs (override takes precedence over base).
- *
- * Performs a shallow merge of two ExtractionConfig structures, where fields
- * from `override_config` take precedence over fields in `base`. The `base`
- * config is modified in-place.
+ * Set the use_cache field.
  *
  * # Arguments
  *
- * * `base` - Pointer to the base ExtractionConfig (will be modified)
- * * `override_config` - Pointer to the override ExtractionConfig (read-only)
+ * * `builder` - Non-null pointer to ConfigBuilder
+ * * `use_cache` - 1 for true, 0 for false
  *
  * # Returns
  *
- * - 1 on success
- * - 0 on error (check `kreuzberg_last_error`)
+ * 0 on success, -1 on error (NULL builder)
  *
  * # Safety
  *
- * - `base` must be a valid mutable pointer to an ExtractionConfig
- * - `override_config` must be a valid pointer to an ExtractionConfig
- * - Neither parameter can be NULL
- * - `base` is modified in-place
+ * This function is meant to be called from C/FFI code. The caller must ensure:
+ * - `builder` must be a valid, non-null pointer previously returned by `kreuzberg_config_builder_new`
+ * - The pointer must be properly aligned and point to a valid ConfigBuilder instance
+ */
+int32_t kreuzberg_config_builder_set_use_cache(struct ConfigBuilder *builder,
+                                               int32_t use_cache);
+
+/**
+ * Set OCR configuration from JSON.
  *
- * # Example (C)
+ * # Arguments
  *
- * ```c
- * ExtractionConfig* base = kreuzberg_config_from_json(
- *     "{\"use_cache\": true, \"force_ocr\": false}"
- * );
- * ExtractionConfig* override = kreuzberg_config_from_json(
- *     "{\"force_ocr\": true}"
- * );
+ * * `builder` - Non-null pointer to ConfigBuilder
+ * * `ocr_json` - JSON string like `{"backend": "tesseract", "languages": ["en"]}`
  *
- * if (kreuzberg_config_merge(base, override) == 1) {
- *     // base now has: use_cache=true, force_ocr=true
- *     char* json = kreuzberg_config_to_json(base);
- *     printf("Merged config: %s\n", json);
- *     kreuzberg_free_string(json);
- * }
+ * # Returns
  *
- * kreuzberg_config_free(base);
- * kreuzberg_config_free(override);
- * ```
+ * 0 on success, -1 on error (check kreuzberg_last_error)
+ *
+ * # Safety
+ *
+ * This function is meant to be called from C/FFI code. The caller must ensure:
+ * - `builder` must be a valid, non-null pointer previously returned by `kreuzberg_config_builder_new`
+ * - The pointer must be properly aligned and point to a valid ConfigBuilder instance
+ * - `ocr_json` must be a valid, non-null pointer to a null-terminated UTF-8 string
+ * - The string pointer must remain valid for the duration of the function call
  */
-int32_t kreuzberg_config_merge(ExtractionConfig *base, const ExtractionConfig *override_config);
+int32_t kreuzberg_config_builder_set_ocr(struct ConfigBuilder *builder,
+                                         const char *ocr_json);
 
 /**
- * Load an ExtractionConfig from a file.
+ * Set PDF configuration from JSON.
+ *
+ * # Arguments
+ *
+ * * `builder` - Non-null pointer to ConfigBuilder
+ * * `pdf_json` - JSON string for PDF config
+ *
+ * # Returns
  *
- * Returns a JSON string representing the loaded configuration.
+ * 0 on success, -1 on error
  *
  * # 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`)
+ * This function is meant to be called from C/FFI code. The caller must ensure:
+ * - `builder` must be a valid, non-null pointer previously returned by `kreuzberg_config_builder_new`
+ * - The pointer must be properly aligned and point to a valid ConfigBuilder instance
+ * - `pdf_json` must be a valid, non-null pointer to a null-terminated UTF-8 string
+ * - The string pointer must remain valid for the duration of the function call
  */
-char *kreuzberg_load_extraction_config_from_file(const char *file_path);
+int32_t kreuzberg_config_builder_set_pdf(struct ConfigBuilder *builder,
+                                         const char *pdf_json);
 
 /**
- * Load an ExtractionConfig from a file (returns pointer to config struct).
+ * Set chunking configuration from JSON.
+ *
+ * # Arguments
+ *
+ * * `builder` - Non-null pointer to ConfigBuilder
+ * * `chunking_json` - JSON string for chunking config
+ *
+ * # Returns
+ *
+ * 0 on success, -1 on error
  *
  * # Safety
  *
- * - `path` must be a valid null-terminated C string
- * - The returned pointer must be freed with `kreuzberg_config_free`
- * - Returns NULL on error (check `kreuzberg_last_error`)
+ * This function is meant to be called from C/FFI code. The caller must ensure:
+ * - `builder` must be a valid, non-null pointer previously returned by `kreuzberg_config_builder_new`
+ * - The pointer must be properly aligned and point to a valid ConfigBuilder instance
+ * - `chunking_json` must be a valid, non-null pointer to a null-terminated UTF-8 string
+ * - The string pointer must remain valid for the duration of the function call
+ */
+int32_t kreuzberg_config_builder_set_chunking(struct ConfigBuilder *builder,
+                                              const char *chunking_json);
+
+/**
+ * Set image extraction configuration from JSON.
  *
- * # Example (C)
+ * # Arguments
  *
- * ```c
- * ExtractionConfig* config = kreuzberg_config_from_file("config.toml");
- * if (config == NULL) {
- *     printf("Error: %s\n", kreuzberg_last_error());
- *     return 1;
- * }
- * kreuzberg_config_free(config);
- * ```
+ * * `builder` - Non-null pointer to ConfigBuilder
+ * * `image_json` - JSON string for image extraction config
+ *
+ * # Returns
+ *
+ * 0 on success, -1 on error
+ *
+ * # Safety
+ *
+ * This function is meant to be called from C/FFI code. The caller must ensure:
+ * - `builder` must be a valid, non-null pointer previously returned by `kreuzberg_config_builder_new`
+ * - The pointer must be properly aligned and point to a valid ConfigBuilder instance
+ * - `image_json` must be a valid, non-null pointer to a null-terminated UTF-8 string
+ * - The string pointer must remain valid for the duration of the function call
  */
-ExtractionConfig *kreuzberg_config_from_file(const char *path);
+int32_t kreuzberg_config_builder_set_image_extraction(struct ConfigBuilder *builder,
+                                                      const char *image_json);
 
 /**
- * Discover and load an ExtractionConfig by searching parent directories.
+ * Set post-processor configuration from JSON.
  *
- * Searches the current directory and all parent directories for:
- * - `kreuzberg.toml`
- * - `kreuzberg.json`
+ * # Arguments
  *
- * Returns the first config file found as a JSON string.
+ * * `builder` - Non-null pointer to ConfigBuilder
+ * * `pp_json` - JSON string for post-processor config
+ *
+ * # Returns
+ *
+ * 0 on success, -1 on error
  *
  * # Safety
  *
- * - The returned string must be freed with `kreuzberg_free_string`
- * - Returns NULL if no config is found or on error
+ * This function is meant to be called from C/FFI code. The caller must ensure:
+ * - `builder` must be a valid, non-null pointer previously returned by `kreuzberg_config_builder_new`
+ * - The pointer must be properly aligned and point to a valid ConfigBuilder instance
+ * - `pp_json` must be a valid, non-null pointer to a null-terminated UTF-8 string
+ * - The string pointer must remain valid for the duration of the function call
+ */
+int32_t kreuzberg_config_builder_set_post_processor(struct ConfigBuilder *builder,
+                                                    const char *pp_json);
+
+/**
+ * Set language detection configuration from JSON.
  *
- * # Example (C)
+ * # Arguments
  *
- * ```c
- * char* config_json = kreuzberg_config_discover();
- * if (config_json != NULL) {
- *     printf("Discovered config: %s\n", config_json);
- *     kreuzberg_free_string(config_json);
- * }
- * ```
+ * * `builder` - Non-null pointer to ConfigBuilder
+ * * `ld_json` - JSON string for language detection config
+ *
+ * # Returns
+ *
+ * 0 on success, -1 on error
+ *
+ * # Safety
+ *
+ * This function is meant to be called from C/FFI code. The caller must ensure:
+ * - `builder` must be a valid, non-null pointer previously returned by `kreuzberg_config_builder_new`
+ * - The pointer must be properly aligned and point to a valid ConfigBuilder instance
+ * - `ld_json` must be a valid, non-null pointer to a null-terminated UTF-8 string
+ * - The string pointer must remain valid for the duration of the function call
  */
-char *kreuzberg_config_discover(void);
+int32_t kreuzberg_config_builder_set_language_detection(struct ConfigBuilder *builder,
+                                                        const char *ld_json);
 
 /**
- * List available embedding preset names.
+ * Build the final ExtractionConfig and consume the builder.
+ *
+ * After calling this function, the builder pointer is invalid and must not be used.
+ * The returned ExtractionConfig must be freed with kreuzberg_config_free().
+ *
+ * # Arguments
+ *
+ * * `builder` - Non-null pointer to ConfigBuilder (will be consumed)
+ *
+ * # Returns
+ *
+ * Pointer to ExtractionConfig on success, NULL on error
  *
  * # Safety
  *
- * - Returned string is a JSON array and must be freed with `kreuzberg_free_string`
- * - Returns NULL on error (check `kreuzberg_last_error`)
+ * - `builder` is consumed and must not be used after this call
+ * - Do NOT call kreuzberg_config_builder_free() after this function
+ * - The returned ExtractionConfig must be freed with kreuzberg_config_free()
  */
-char *kreuzberg_list_embedding_presets(void);
+ExtractionConfig *kreuzberg_config_builder_build(struct ConfigBuilder *builder);
 
 /**
- * Get a specific embedding preset by name.
+ * Free a ConfigBuilder without building.
+ *
+ * Use this to discard a builder without creating a config.
+ * Do NOT call this after kreuzberg_config_builder_build() (builder is already consumed).
+ *
+ * # Arguments
+ *
+ * * `builder` - Pointer to ConfigBuilder, can be NULL (no-op)
  *
  * # 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`)
+ * - `builder` can be NULL (no-op)
+ * - Do NOT call this after kreuzberg_config_builder_build()
  */
-char *kreuzberg_get_embedding_preset(const char *name);
+void kreuzberg_config_builder_free(struct ConfigBuilder *builder);
 
 /**
  * Returns the validation error code (0).
@@ -1370,6 +1418,127 @@ struct CBatchResult *kreuzberg_batch_extract_bytes_sync(const struct CBytesWithM
                                                         uintptr_t count,
                                                         const char *config_json);
 
+/**
+ * Parse HeadingStyle from string to discriminant.
+ *
+ * Valid values: "atx", "underlined", "atx_closed" | "atx-closed"
+ * Returns: 0 = Atx, 1 = Underlined, 2 = AtxClosed, -1 = Invalid
+ *
+ * # Safety
+ *
+ * - `value` must be a valid null-terminated C string or NULL
+ */
+int32_t kreuzberg_parse_heading_style(const char *value);
+
+/**
+ * Convert HeadingStyle discriminant to string.
+ *
+ * Returns: pointer to static string, or NULL for invalid discriminant
+ */
+const char *kreuzberg_heading_style_to_string(int32_t discriminant);
+
+/**
+ * Parse CodeBlockStyle from string to discriminant.
+ *
+ * Valid values: "indented", "backticks", "tildes"
+ * Returns: 0 = Indented, 1 = Backticks, 2 = Tildes, -1 = Invalid
+ *
+ * # Safety
+ *
+ * - `value` must be a valid null-terminated C string or NULL
+ */
+int32_t kreuzberg_parse_code_block_style(const char *value);
+
+/**
+ * Convert CodeBlockStyle discriminant to string.
+ */
+const char *kreuzberg_code_block_style_to_string(int32_t discriminant);
+
+/**
+ * Parse HighlightStyle from string to discriminant.
+ *
+ * Valid values: "double_equal" | "==" | "double-equal", "html", "bold", "none"
+ * Returns: 0 = DoubleEqual, 1 = Html, 2 = Bold, 3 = None, -1 = Invalid
+ *
+ * # Safety
+ *
+ * - `value` must be a valid null-terminated C string or NULL
+ */
+int32_t kreuzberg_parse_highlight_style(const char *value);
+
+/**
+ * Convert HighlightStyle discriminant to string.
+ */
+const char *kreuzberg_highlight_style_to_string(int32_t discriminant);
+
+/**
+ * Parse ListIndentType from string to discriminant.
+ *
+ * Valid values: "spaces", "tabs"
+ * Returns: 0 = Spaces, 1 = Tabs, -1 = Invalid
+ *
+ * # Safety
+ *
+ * - `value` must be a valid null-terminated C string or NULL
+ */
+int32_t kreuzberg_parse_list_indent_type(const char *value);
+
+/**
+ * Convert ListIndentType discriminant to string.
+ */
+const char *kreuzberg_list_indent_type_to_string(int32_t discriminant);
+
+/**
+ * Parse WhitespaceMode from string to discriminant.
+ *
+ * Valid values: "default", "preserve", "preserve_inner", "collapse"
+ * Returns: 0 = Default, 1 = Preserve, 2 = PreserveInner, 3 = Collapse, -1 = Invalid
+ *
+ * # Safety
+ *
+ * - `value` must be a valid null-terminated C string or NULL
+ */
+int32_t kreuzberg_parse_whitespace_mode(const char *value);
+
+/**
+ * Convert WhitespaceMode discriminant to string.
+ */
+const char *kreuzberg_whitespace_mode_to_string(int32_t discriminant);
+
+/**
+ * Parse NewlineStyle from string to discriminant.
+ *
+ * Valid values: "default", "spaces", "backslash"
+ * Returns: 0 = Default, 1 = Spaces, 2 = Backslash, -1 = Invalid
+ *
+ * # Safety
+ *
+ * - `value` must be a valid null-terminated C string or NULL
+ */
+int32_t kreuzberg_parse_newline_style(const char *value);
+
+/**
+ * Convert NewlineStyle discriminant to string.
+ */
+const char *kreuzberg_newline_style_to_string(int32_t discriminant);
+
+/**
+ * Parse PreprocessingPreset from string to discriminant.
+ *
+ * Valid values: "none", "conservative", "aggressive"
+ * Returns: 0 = None, 1 = Conservative, 2 = Aggressive, -1 = Invalid
+ *
+ * # Safety
+ *
+ * - `value` must be a valid null-terminated C string or NULL
+ */
+int32_t kreuzberg_parse_preprocessing_preset(const char *value);
+
+/**
+ * Convert PreprocessingPreset discriminant to string.
+ */
+const char *kreuzberg_preprocessing_preset_to_string(int32_t discriminant);
+
 /**
  * Free a batch result returned by batch extraction functions.
  *