Merge pull request #386 from kreuzberg-dev/fix-rust-docs

Align core Rust API docs and snippets

Author: Goldziher

crates/kreuzberg/src/core/config/extraction/core.rs

@@ -87,10 +87,10 @@ pub struct ExtractionConfig {
     #[serde(default)]
     pub html_options: Option<html_to_markdown_rs::ConversionOptions>,
 
-    /// Maximum concurrent extractions in batch operations (None = num_cpus * 2).
+    /// Maximum concurrent extractions in batch operations (None = (num_cpus × 1.5).ceil()).
     ///
     /// Limits parallelism to prevent resource exhaustion when processing
-    /// large batches. Defaults to twice the number of CPU cores.
+    /// large batches. Defaults to (num_cpus × 1.5).ceil() when not set.
     #[serde(default)]
     pub max_concurrent_extractions: Option<usize>,
 

crates/kreuzberg/src/core/extractor/batch.rs

@@ -19,7 +19,7 @@ use super::file::extract_file;
 /// This function processes multiple files in parallel, automatically managing
 /// concurrency to prevent resource exhaustion. The concurrency limit can be
 /// configured via `ExtractionConfig::max_concurrent_extractions` or defaults
-/// to `num_cpus * 2`.
+/// to `(num_cpus * 1.5).ceil()`.
 ///
 /// # Arguments
 ///
@@ -153,7 +153,7 @@ pub async fn batch_extract_file(
 /// This function processes multiple byte arrays in parallel, automatically managing
 /// concurrency to prevent resource exhaustion. The concurrency limit can be
 /// configured via `ExtractionConfig::max_concurrent_extractions` or defaults
-/// to `num_cpus * 2`.
+/// to `(num_cpus * 1.5).ceil()`.
 ///
 /// # Arguments
 ///

crates/kreuzberg/src/plugins/mod.rs

@@ -41,7 +41,7 @@
 //! #         -> kreuzberg::Result<ExtractionResult> {
 //! #         Ok(ExtractionResult {
 //! #             content: String::new(),
-//! #             mime_type: String::new().into(),
+//! #             mime_type: std::borrow::Cow::Borrowed("text/plain"),
 //! #             metadata: Metadata::default(),
 //! #             tables: vec![],
 //! #             detected_languages: None,
@@ -130,7 +130,7 @@
 //!
 //!         Ok(ExtractionResult {
 //!             content: extracted_text,
-//!             mime_type: "application/json".to_string().into(),
+//!             mime_type: std::borrow::Cow::Borrowed("application/json"),
 //!             metadata,
 //!             tables: vec![],
 //!             detected_languages: None,

crates/kreuzberg/src/plugins/ocr.rs

@@ -43,8 +43,8 @@ pub enum OcrBackendType {
 /// use kreuzberg::plugins::{Plugin, OcrBackend, OcrBackendType};
 /// use kreuzberg::{Result, OcrConfig};
 /// use async_trait::async_trait;
-/// use std::path::Path;
 /// use std::borrow::Cow;
+/// use std::path::Path;
 /// use kreuzberg::types::{ExtractionResult, Metadata};
 ///
 /// struct CustomOcrBackend;
@@ -119,8 +119,8 @@ pub trait OcrBackend: Plugin {
     /// # use kreuzberg::plugins::{Plugin, OcrBackend};
     /// # use kreuzberg::{Result, OcrConfig};
     /// # use async_trait::async_trait;
-    /// # use std::path::Path;
     /// # use std::borrow::Cow;
+    /// # use std::path::Path;
     /// # use kreuzberg::types::{ExtractionResult, Metadata};
     /// # struct MyOcr;
     /// # impl Plugin for MyOcr {
@@ -310,9 +310,9 @@ pub trait OcrBackend: Plugin {
 /// use kreuzberg::{Result, OcrConfig};
 /// use kreuzberg::types::{ExtractionResult, Metadata};
 /// use async_trait::async_trait;
+/// use std::borrow::Cow;
 /// use std::sync::Arc;
 /// use std::path::Path;
-/// use std::borrow::Cow;
 ///
 /// struct CustomOcr;
 ///

crates/kreuzberg/src/types/extraction.rs

@@ -50,9 +50,9 @@ pub struct ExtractionResult {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub pages: Option<Vec<PageContent>>,
 
-    /// Semantic elements when element-based output format is enabled.
+    /// Semantic elements when element-based result format is enabled.
     ///
-    /// When output_format is set to ElementBased, this field contains semantic
+    /// When result_format is set to ElementBased, this field contains semantic
     /// elements with type classification, unique identifiers, and metadata for
     /// Unstructured-compatible element-based processing.
     #[serde(skip_serializing_if = "Option::is_none", default)]

docs/cli/usage.md

@@ -25,7 +25,7 @@ The Kreuzberg CLI provides command-line access to all extraction features. This
     --8<-- "snippets/cli/install_go_sdk.md"
 
 !!! info "Feature Availability"
-    **Homebrew Installation:**
+**Homebrew Installation:**
 
     - ✅ Text extraction (PDF, Office, images, 75+ formats)
     - ✅ OCR with Tesseract
@@ -165,22 +165,37 @@ Configure OCR backend, language, and Tesseract options in your config file (see
 
 ### Using Config Files
 
-Kreuzberg automatically discovers configuration files by searching the current directory and parent directories for:
-
-1. `./kreuzberg.{toml,yaml,yml,json}` in the current directory
-2. `../kreuzberg.{toml,yaml,yml,json}` in the parent directory (and so on, up the directory tree)
+Kreuzberg automatically discovers a configuration file by searching the current directory and parent directories for **`kreuzberg.toml`** only. If you use YAML or JSON, specify the file explicitly with `--config`.
 
 ```bash title="Terminal"
-# Extract using discovered configuration
+# Extract using discovered configuration (finds kreuzberg.toml)
 kreuzberg extract document.pdf
 ```
 
 ### Specify Config File
 
+You can load TOML, YAML (`.yaml` or `.yml`), or JSON via `--config`:
+
 ```bash title="Terminal"
 kreuzberg extract document.pdf --config my-config.toml
+kreuzberg extract document.pdf --config kreuzberg.yaml
+kreuzberg extract document.pdf --config my-config.json
+```
+
+### Inline JSON Config
+
+Override or supply config without a file using inline JSON (merged after config file, before individual flags):
+
+```bash title="Terminal"
+# Inline JSON (applied after config file)
+kreuzberg extract document.pdf --config-json '{"ocr":{"backend":"tesseract"},"chunking":{"max_chars":1000}}'
+
+# Base64-encoded JSON (useful in shells where quoting is awkward)
+kreuzberg extract document.pdf --config-json-base64 eyJvY3IiOnsiYmFja2VuZCI6InRlc3NlcmFjdCJ9fQ==
 ```
 
+Both `extract` and `batch` support `--config-json` and `--config-json-base64`.
+
 ### Example Config Files
 
 **kreuzberg.toml:**
@@ -447,23 +462,25 @@ kreuzberg detect document.pdf
 
 ## Docker Usage
 
+Use the CLI image `ghcr.io/kreuzberg-dev/kreuzberg-cli:latest` for command-line usage. The full image `ghcr.io/kreuzberg-dev/kreuzberg:latest` also includes the CLI.
+
 ### Basic Docker
 
 ```bash title="Terminal"
 # Extract document using Docker with mounted directory
-docker run -v $(pwd):/data ghcr.io/kreuzberg-dev/kreuzberg:latest \
+docker run -v $(pwd):/data ghcr.io/kreuzberg-dev/kreuzberg-cli:latest \
   extract /data/document.pdf
 
 # Extract and save output to host directory using shell redirection
-docker run -v $(pwd):/data ghcr.io/kreuzberg-dev/kreuzberg:latest \
+docker run -v $(pwd):/data ghcr.io/kreuzberg-dev/kreuzberg-cli:latest \
   extract /data/document.pdf > output.txt
 ```
 
 ### Docker with OCR
 
 ```bash title="Terminal"
 # Extract with OCR using Docker
-docker run -v $(pwd):/data ghcr.io/kreuzberg-dev/kreuzberg:latest \
+docker run -v $(pwd):/data ghcr.io/kreuzberg-dev/kreuzberg-cli:latest \
   extract /data/scanned.pdf --ocr true
 ```
 
@@ -472,11 +489,11 @@ docker run -v $(pwd):/data ghcr.io/kreuzberg-dev/kreuzberg:latest \
 **docker-compose.yaml:**
 
 ```yaml title="docker-compose.yaml"
-version: '3.8'
+version: "3.8"
 
 services:
   kreuzberg:
-    image: ghcr.io/kreuzberg-dev/kreuzberg:latest
+    image: ghcr.io/kreuzberg-dev/kreuzberg-cli:latest
     volumes:
       - ./documents:/input
     command: extract /input/document.pdf --ocr true
@@ -558,8 +575,9 @@ The `serve` command starts a RESTful HTTP API server:
 # Start server on default host (127.0.0.1) and port (8000)
 kreuzberg serve
 
-# Start server on specific host and port
+# Start server on specific host and port (-H / -p are short forms)
 kreuzberg serve --host 0.0.0.0 --port 8000
+kreuzberg serve -H 0.0.0.0 -p 8000
 
 # Start server with custom configuration file
 kreuzberg serve --config kreuzberg.toml --host 0.0.0.0 --port 8000
@@ -568,6 +586,7 @@ kreuzberg serve --config kreuzberg.toml --host 0.0.0.0 --port 8000
 ### Server Endpoints
 
 The server provides the following endpoints:
+
 - `POST /extract` - Extract text from uploaded files
 - `POST /batch` - Batch extract from multiple files
 - `GET /detect` - Detect MIME type of file
@@ -597,6 +616,7 @@ kreuzberg mcp --config kreuzberg.toml --transport stdio
 ```
 
 The MCP server provides tools for AI agents:
+
 - `extract_file` - Extract text from a file path
 - `extract_bytes` - Extract text from base64-encoded bytes
 - `batch_extract` - Extract from multiple files
@@ -643,9 +663,12 @@ kreuzberg --help
 kreuzberg extract --help
 kreuzberg batch --help
 kreuzberg detect --help
+kreuzberg version --help
 kreuzberg serve --help
 kreuzberg mcp --help
 kreuzberg cache --help
+kreuzberg cache stats --help
+kreuzberg cache clear --help
 ```
 
 ### Version Information

docs/concepts/mime-detection.md

@@ -59,13 +59,11 @@ let mime_type = EXT_TO_MIME.get(extension.as_str())
 Whether the MIME type was detected or explicitly provided, it must be supported:
 
 ```rust title="mime_detection.rs"
-pub fn validate_mime_type(mime_type: &str) -> Result<()> {
+pub fn validate_mime_type(mime_type: &str) -> Result<String> {
     if SUPPORTED_TYPES.contains(mime_type) {
-        Ok(())
+        Ok(mime_type.to_string())
     } else {
-        Err(KreuzbergError::UnsupportedFormat {
-            mime_type: mime_type.to_string(),
-        })
+        Err(KreuzbergError::UnsupportedFormat(mime_type.to_string()))
     }
 }
 ```
@@ -76,80 +74,80 @@ Kreuzberg supports multiple file formats across many categories:
 
 ### Documents
 
-| Extension | MIME Type |
-|-----------|-----------|
-| `.pdf` | `application/pdf` |
-| `.docx` | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |
-| `.doc` | `application/msword` |
-| `.odt` | `application/vnd.oasis.opendocument.text` |
-| `.rtf` | `application/rtf` |
+| Extension | MIME Type                                                                 |
+| --------- | ------------------------------------------------------------------------- |
+| `.pdf`    | `application/pdf`                                                         |
+| `.docx`   | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |
+| `.doc`    | `application/msword`                                                      |
+| `.odt`    | `application/vnd.oasis.opendocument.text`                                 |
+| `.rtf`    | `application/rtf`                                                         |
 
 ### Spreadsheets
 
-| Extension | MIME Type |
-|-----------|-----------|
-| `.xlsx` | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` |
-| `.xls` | `application/vnd.ms-excel` |
-| `.xlsm` | `application/vnd.ms-excel.sheet.macroEnabled.12` |
-| `.xlsb` | `application/vnd.ms-excel.sheet.binary.macroEnabled.12` |
-| `.ods` | `application/vnd.oasis.opendocument.spreadsheet` |
-| `.csv` | `text/csv` |
-| `.tsv` | `text/tab-separated-values` |
+| Extension | MIME Type                                                           |
+| --------- | ------------------------------------------------------------------- |
+| `.xlsx`   | `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` |
+| `.xls`    | `application/vnd.ms-excel`                                          |
+| `.xlsm`   | `application/vnd.ms-excel.sheet.macroEnabled.12`                    |
+| `.xlsb`   | `application/vnd.ms-excel.sheet.binary.macroEnabled.12`             |
+| `.ods`    | `application/vnd.oasis.opendocument.spreadsheet`                    |
+| `.csv`    | `text/csv`                                                          |
+| `.tsv`    | `text/tab-separated-values`                                         |
 
 ### Presentations
 
-| Extension | MIME Type |
-|-----------|-----------|
-| `.pptx` | `application/vnd.openxmlformats-officedocument.presentationml.presentation` |
-| `.ppt` | `application/vnd.ms-powerpoint` |
-| `.odp` | `application/vnd.oasis.opendocument.presentation` |
+| Extension | MIME Type                                                                   |
+| --------- | --------------------------------------------------------------------------- |
+| `.pptx`   | `application/vnd.openxmlformats-officedocument.presentationml.presentation` |
+| `.ppt`    | `application/vnd.ms-powerpoint`                                             |
+| `.odp`    | `application/vnd.oasis.opendocument.presentation`                           |
 
 ### Images
 
-| Extension | MIME Type |
-|-----------|-----------|
-| `.jpg`, `.jpeg` | `image/jpeg` |
-| `.png` | `image/png` |
-| `.gif` | `image/gif` |
-| `.bmp` | `image/bmp` |
-| `.tiff`, `.tif` | `image/tiff` |
-| `.webp` | `image/webp` |
-| `.svg` | `image/svg+xml` |
+| Extension       | MIME Type       |
+| --------------- | --------------- |
+| `.jpg`, `.jpeg` | `image/jpeg`    |
+| `.png`          | `image/png`     |
+| `.gif`          | `image/gif`     |
+| `.bmp`          | `image/bmp`     |
+| `.tiff`, `.tif` | `image/tiff`    |
+| `.webp`         | `image/webp`    |
+| `.svg`          | `image/svg+xml` |
 
 ### Text and Markup
 
-| Extension | MIME Type |
-|-----------|-----------|
-| `.txt` | `text/plain` |
-| `.md`, `.markdown` | `text/markdown` |
-| `.html`, `.htm` | `text/html` |
-| `.xml` | `application/xml` |
-| `.json` | `application/json` |
-| `.yaml` | `application/x-yaml` |
-| `.toml` | `application/toml` |
+| Extension          | MIME Type            |
+| ------------------ | -------------------- |
+| `.txt`             | `text/plain`         |
+| `.md`, `.markdown` | `text/markdown`      |
+| `.html`, `.htm`    | `text/html`          |
+| `.xml`             | `application/xml`    |
+| `.json`            | `application/json`   |
+| `.yaml`            | `application/x-yaml` |
+| `.toml`            | `application/toml`   |
 
 ### Email
 
-| Extension | MIME Type |
-|-----------|-----------|
-| `.eml` | `message/rfc822` |
-| `.msg` | `application/vnd.ms-outlook` |
+| Extension | MIME Type                    |
+| --------- | ---------------------------- |
+| `.eml`    | `message/rfc822`             |
+| `.msg`    | `application/vnd.ms-outlook` |
 
 ### Archives
 
-| Extension | MIME Type |
-|-----------|-----------|
-| `.zip` | `application/zip` |
-| `.tar` | `application/x-tar` |
-| `.gz` | `application/gzip` |
-| `.7z` | `application/x-7z-compressed` |
+| Extension | MIME Type                     |
+| --------- | ----------------------------- |
+| `.zip`    | `application/zip`             |
+| `.tar`    | `application/x-tar`           |
+| `.gz`     | `application/gzip`            |
+| `.7z`     | `application/x-7z-compressed` |
 
 ### Ebooks
 
-| Extension | MIME Type |
-|-----------|-----------|
-| `.epub` | `application/epub+zip` |
-| `.mobi` | `application/x-mobipocket-ebook` |
+| Extension | MIME Type                        |
+| --------- | -------------------------------- |
+| `.epub`   | `application/epub+zip`           |
+| `.mobi`   | `application/x-mobipocket-ebook` |
 
 ## Explicit MIME Type Override
 
@@ -189,15 +187,15 @@ result = extract_file("document.pdf", mime_type=PDF_MIME_TYPE, config=config)
 Kreuzberg provides utility functions for MIME type operations:
 
 ```rust title="mime_detection.rs"
-// Automatically detect MIME type from file path extension
-pub fn detect_mime_type(path: impl AsRef<Path>) -> Result<String>
+// Detect MIME type from file path (by extension). check_exists: if true, file must exist.
+pub fn detect_mime_type(path: impl AsRef<Path>, check_exists: bool) -> Result<String>
 
-// Verify that a MIME type is supported by Kreuzberg
-pub fn validate_mime_type(mime_type: &str) -> Result<()>
+// Validate that a MIME type is supported; returns the validated (possibly normalized) string.
+pub fn validate_mime_type(mime_type: &str) -> Result<String>
 
-// Auto-detect MIME type or validate explicit type if provided
+// If mime_type provided, validate it; else detect from path. Errors if both are None.
 pub fn detect_or_validate(
-    path: impl AsRef<Path>,
+    path: Option<&Path>,
     mime_type: Option<&str>
 ) -> Result<String>
 ```