kreuzberg 4.2.1 → 4.2.2

data/vendor/kreuzberg/src/api/openapi.rs

@@ -0,0 +1,141 @@
+//! OpenAPI 3.1 schema generation for Kreuzberg API.
+//!
+//! This module generates OpenAPI documentation from Rust types using utoipa.
+//! The schema is available at the `/openapi.json` endpoint.
+
+#[cfg(feature = "api")]
+use utoipa::OpenApi;
+
+/// OpenAPI documentation structure.
+///
+/// Defines all endpoints, request/response schemas, and examples
+/// for the Kreuzberg document extraction API.
+#[cfg(feature = "api")]
+#[derive(OpenApi)]
+#[openapi(
+    info(
+        title = "Kreuzberg API",
+        version = env!("CARGO_PKG_VERSION"),
+        description = "High-performance document intelligence API for extracting text, metadata, and structured data from PDFs, Office documents, images, and 50+ formats.",
+        contact(
+            name = "Kreuzberg",
+            url = "https://kreuzberg.dev"
+        ),
+        license(
+            name = "Apache-2.0 OR MIT"
+        )
+    ),
+    servers(
+        (url = "http://localhost:8000", description = "Local development server"),
+        (url = "https://api.kreuzberg.dev", description = "Production server (example)")
+    ),
+    paths(
+        crate::api::handlers::health_handler,
+        crate::api::handlers::info_handler,
+        // Note: extract_handler omitted - requires ExtractionResult ToSchema impl
+        crate::api::handlers::cache_stats_handler,
+        crate::api::handlers::cache_clear_handler,
+        crate::api::handlers::embed_handler,
+        crate::api::handlers::chunk_handler,
+    ),
+    components(
+        schemas(
+            crate::api::types::HealthResponse,
+            crate::api::types::PluginStatus,
+            crate::api::types::InfoResponse,
+            crate::api::types::ErrorResponse,
+            crate::api::types::CacheStatsResponse,
+            crate::api::types::CacheClearResponse,
+            crate::api::types::EmbedRequest,
+            crate::api::types::EmbedResponse,
+            crate::api::types::ChunkRequest,
+            crate::api::types::ChunkResponse,
+            crate::api::types::ChunkItem,
+            crate::api::types::ChunkingConfigRequest,
+            crate::api::types::ChunkingConfigResponse,
+        )
+    ),
+    tags(
+        (name = "health", description = "Health and status endpoints"),
+        (name = "extraction", description = "Document extraction endpoints"),
+        (name = "cache", description = "Cache management endpoints"),
+        (name = "embeddings", description = "Text embedding generation"),
+        (name = "chunking", description = "Text chunking operations")
+    )
+)]
+pub struct ApiDoc;
+
+/// Generate OpenAPI JSON schema.
+///
+/// Returns the complete OpenAPI 3.1 specification as a JSON string.
+///
+/// # Examples
+///
+/// ```no_run
+/// use kreuzberg::api::openapi::openapi_json;
+///
+/// let schema = openapi_json();
+/// println!("{}", schema);
+/// ```
+#[cfg(feature = "api")]
+pub fn openapi_json() -> String {
+    ApiDoc::openapi().to_pretty_json().unwrap_or_else(|_| "{}".to_string())
+}
+
+#[cfg(not(feature = "api"))]
+pub fn openapi_json() -> String {
+    r#"{"error": "API feature not enabled"}"#.to_string()
+}
+
+#[cfg(test)]
+mod tests {
+    #[cfg(feature = "api")]
+    use super::*;
+
+    #[test]
+    #[cfg(feature = "api")]
+    fn test_openapi_schema_generation() {
+        let schema = openapi_json();
+        assert!(!schema.is_empty());
+        assert!(schema.contains("Kreuzberg API"));
+        assert!(schema.contains("/health"));
+        assert!(schema.contains("/extract"));
+    }
+
+    #[test]
+    #[cfg(feature = "api")]
+    fn test_openapi_schema_valid_json() {
+        let schema = openapi_json();
+        let parsed: serde_json::Value = serde_json::from_str(&schema).expect("Invalid JSON");
+        assert!(parsed.is_object());
+        assert!(parsed["openapi"].is_string());
+    }
+
+    #[test]
+    #[cfg(feature = "api")]
+    fn test_openapi_includes_all_endpoints() {
+        let schema = openapi_json();
+        // Health endpoints
+        assert!(schema.contains("/health"));
+        assert!(schema.contains("/info"));
+        // Extraction
+        assert!(schema.contains("/extract"));
+        // Cache
+        assert!(schema.contains("/cache/stats"));
+        assert!(schema.contains("/cache/clear"));
+        // Embeddings
+        assert!(schema.contains("/embed"));
+        // Chunking
+        assert!(schema.contains("/chunk"));
+    }
+
+    #[test]
+    #[cfg(feature = "api")]
+    fn test_openapi_includes_schemas() {
+        let schema = openapi_json();
+        assert!(schema.contains("HealthResponse"));
+        assert!(schema.contains("ErrorResponse"));
+        assert!(schema.contains("EmbedRequest"));
+        assert!(schema.contains("ChunkRequest"));
+    }
+}

data/vendor/kreuzberg/src/api/router.rs

@@ -153,14 +153,22 @@ pub fn create_router_with_limits_and_server_config(
         }
     };
 
-    Router::new()
+    let mut router = Router::new()
         .route("/extract", post(extract_handler))
         .route("/embed", post(embed_handler))
         .route("/chunk", post(chunk_handler))
         .route("/health", get(health_handler))
         .route("/info", get(info_handler))
         .route("/cache/stats", get(cache_stats_handler))
-        .route("/cache/clear", delete(cache_clear_handler))
+        .route("/cache/clear", delete(cache_clear_handler));
+
+    // Add OpenAPI schema endpoint if API feature is enabled
+    #[cfg(feature = "api")]
+    {
+        router = router.route("/openapi.json", get(openapi_schema_handler));
+    }
+
+    router
         .layer(DefaultBodyLimit::max(limits.max_request_body_bytes))
         .layer(RequestBodyLimitLayer::new(limits.max_request_body_bytes))
         .layer(cors_layer)
@@ -168,6 +176,20 @@ pub fn create_router_with_limits_and_server_config(
         .with_state(state)
 }
 
+/// OpenAPI schema handler.
+///
+/// Returns the OpenAPI 3.1 JSON schema for all documented endpoints.
+#[cfg(feature = "api")]
+async fn openapi_schema_handler() -> axum::Json<serde_json::Value> {
+    use crate::api::openapi::openapi_json;
+
+    let schema_str = openapi_json();
+    let schema: serde_json::Value = serde_json::from_str(&schema_str)
+        .unwrap_or_else(|_| serde_json::json!({"error": "Failed to generate OpenAPI schema"}));
+
+    axum::Json(schema)
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

data/vendor/kreuzberg/src/api/startup.rs

@@ -2,7 +2,9 @@
 
 use std::net::{IpAddr, SocketAddr};
 
-use crate::{ExtractionConfig, Result, core::ServerConfig, plugins::startup_validation::validate_plugins_at_startup};
+use crate::{
+    ExtractionConfig, Result, core::ServerConfig, extractors, plugins::startup_validation::validate_plugins_at_startup,
+};
 
 use super::{config::load_server_config, router::create_router_with_limits_and_server_config, types::ApiSizeLimits};
 
@@ -80,7 +82,8 @@ pub async fn serve(host: impl AsRef<str>, port: u16) -> Result<()> {
         server_config.max_multipart_field_bytes,
     );
 
-    // Validate plugins at startup
+    // Initialize extractors and validate plugins at startup
+    extractors::ensure_initialized()?;
     validate_plugins_at_startup()?;
 
     serve_with_config_and_limits(host, port, extraction_config, limits).await
@@ -115,7 +118,8 @@ pub async fn serve_with_config(host: impl AsRef<str>, port: u16, config: Extract
         limits.max_request_body_bytes
     );
 
-    // Validate plugins at startup
+    // Initialize extractors and validate plugins at startup
+    extractors::ensure_initialized()?;
     validate_plugins_at_startup()?;
 
     serve_with_config_and_limits(host, port, config, limits).await
@@ -165,7 +169,8 @@ pub async fn serve_with_config_and_limits(
     let addr = SocketAddr::new(ip, port);
     let app = create_router_with_limits_and_server_config(config, limits, server_config);
 
-    // Validate plugins at startup
+    // Initialize extractors and validate plugins at startup
+    extractors::ensure_initialized()?;
     validate_plugins_at_startup()?;
 
     tracing::info!("Starting Kreuzberg API server on http://{}:{}", ip, port);
@@ -224,7 +229,8 @@ pub async fn serve_with_server_config(extraction_config: ExtractionConfig, serve
     let addr = SocketAddr::new(ip, server_config.port);
     let app = create_router_with_limits_and_server_config(extraction_config, limits, server_config.clone());
 
-    // Validate plugins at startup
+    // Initialize extractors and validate plugins at startup
+    extractors::ensure_initialized()?;
     validate_plugins_at_startup()?;
 
     tracing::info!(

data/vendor/kreuzberg/src/api/types.rs

@@ -109,19 +109,41 @@ impl ApiSizeLimits {
     }
 }
 
+/// Plugin status information in health response.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "api", derive(utoipa::ToSchema))]
+pub struct PluginStatus {
+    /// Number of registered OCR backends
+    pub ocr_backends_count: usize,
+    /// Names of registered OCR backends
+    pub ocr_backends: Vec<String>,
+    /// Number of registered document extractors
+    pub extractors_count: usize,
+    /// Number of registered post-processors
+    pub post_processors_count: usize,
+}
+
 /// Health check response.
 #[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "api", derive(utoipa::ToSchema))]
 pub struct HealthResponse {
     /// Health status
+    #[cfg_attr(feature = "api", schema(example = "healthy"))]
     pub status: String,
     /// API version
+    #[cfg_attr(feature = "api", schema(example = "0.8.0"))]
     pub version: String,
+    /// Plugin status (optional)
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub plugins: Option<PluginStatus>,
 }
 
 /// Server information response.
 #[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "api", derive(utoipa::ToSchema))]
 pub struct InfoResponse {
     /// API version
+    #[cfg_attr(feature = "api", schema(example = "0.8.0"))]
     pub version: String,
     /// Whether using Rust backend
     pub rust_backend: bool,
@@ -132,15 +154,19 @@ pub type ExtractResponse = Vec<ExtractionResult>;
 
 /// Error response.
 #[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "api", derive(utoipa::ToSchema))]
 pub struct ErrorResponse {
     /// Error type name
+    #[cfg_attr(feature = "api", schema(example = "ValidationError"))]
     pub error_type: String,
     /// Error message
+    #[cfg_attr(feature = "api", schema(example = "Invalid input provided"))]
     pub message: String,
     /// Stack trace (if available)
     #[serde(skip_serializing_if = "Option::is_none")]
     pub traceback: Option<String>,
     /// HTTP status code
+    #[cfg_attr(feature = "api", schema(example = 400))]
     pub status_code: u16,
 }
 
@@ -156,8 +182,10 @@ pub struct ApiState {
 
 /// Cache statistics response.
 #[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "api", derive(utoipa::ToSchema))]
 pub struct CacheStatsResponse {
     /// Cache directory path
+    #[cfg_attr(feature = "api", schema(example = "/tmp/kreuzberg-cache"))]
     pub directory: String,
     /// Total number of cache files
     pub total_files: usize,
@@ -173,8 +201,10 @@ pub struct CacheStatsResponse {
 
 /// Cache clear response.
 #[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "api", derive(utoipa::ToSchema))]
 pub struct CacheClearResponse {
     /// Cache directory path
+    #[cfg_attr(feature = "api", schema(example = "/tmp/kreuzberg-cache"))]
     pub directory: String,
     /// Number of files removed
     pub removed_files: usize,
@@ -184,20 +214,25 @@ pub struct CacheClearResponse {
 
 /// Embedding request for generating embeddings from text.
 #[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "api", derive(utoipa::ToSchema))]
 pub struct EmbedRequest {
-    /// Text strings to generate embeddings for
+    /// Text strings to generate embeddings for (at least one non-empty string required)
+    #[cfg_attr(feature = "api", schema(min_items = 1))]
     pub texts: Vec<String>,
     /// Optional embedding configuration (model, batch size, etc.)
     #[serde(skip_serializing_if = "Option::is_none")]
+    #[cfg_attr(feature = "api", schema(value_type = Option<Object>))]
     pub config: Option<crate::core::config::EmbeddingConfig>,
 }
 
 /// Embedding response containing generated embeddings.
 #[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "api", derive(utoipa::ToSchema))]
 pub struct EmbedResponse {
     /// Generated embeddings (one per input text)
     pub embeddings: Vec<Vec<f32>>,
     /// Model used for embedding generation
+    #[cfg_attr(feature = "api", schema(example = "all-MiniLM-L6-v2"))]
     pub model: String,
     /// Dimensionality of the embeddings
     pub dimensions: usize,
@@ -212,23 +247,29 @@ fn default_chunker_type() -> String {
 
 /// Chunk request with text and configuration.
 #[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "api", derive(utoipa::ToSchema))]
 pub struct ChunkRequest {
-    /// Text to chunk
+    /// Text to chunk (must not be empty)
+    #[cfg_attr(feature = "api", schema(example = "This is sample text to chunk.", min_length = 1))]
     pub text: String,
     /// Optional chunking configuration
     #[serde(skip_serializing_if = "Option::is_none")]
     pub config: Option<ChunkingConfigRequest>,
     /// Chunker type (text or markdown)
     #[serde(default = "default_chunker_type")]
+    #[cfg_attr(feature = "api", schema(example = "text", pattern = "^(text|markdown)$"))]
     pub chunker_type: String,
 }
 
 /// Chunking configuration request.
 #[derive(Debug, Clone, Default, Serialize, Deserialize)]
+#[cfg_attr(feature = "api", derive(utoipa::ToSchema))]
 pub struct ChunkingConfigRequest {
-    /// Maximum characters per chunk
+    /// Maximum characters per chunk (must be greater than overlap, default: 2000)
+    #[cfg_attr(feature = "api", schema(minimum = 101, example = 2000))]
     pub max_characters: Option<usize>,
-    /// Overlap between chunks in characters
+    /// Overlap between chunks in characters (must be less than max_characters, default: 100)
+    #[cfg_attr(feature = "api", schema(minimum = 0, maximum = 1999, example = 100))]
     pub overlap: Option<usize>,
     /// Whether to trim whitespace
     pub trim: Option<bool>,
@@ -236,6 +277,7 @@ pub struct ChunkingConfigRequest {
 
 /// Chunk response with chunks and metadata.
 #[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "api", derive(utoipa::ToSchema))]
 pub struct ChunkResponse {
     /// List of chunks
     pub chunks: Vec<ChunkItem>,
@@ -246,11 +288,13 @@ pub struct ChunkResponse {
     /// Input text size in bytes
     pub input_size_bytes: usize,
     /// Chunker type used for chunking
+    #[cfg_attr(feature = "api", schema(example = "text"))]
     pub chunker_type: String,
 }
 
 /// Individual chunk item with metadata.
 #[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "api", derive(utoipa::ToSchema))]
 pub struct ChunkItem {
     /// Chunk content
     pub content: String,
@@ -272,6 +316,7 @@ pub struct ChunkItem {
 
 /// Chunking configuration response.
 #[derive(Debug, Clone, Serialize, Deserialize)]
+#[cfg_attr(feature = "api", derive(utoipa::ToSchema))]
 pub struct ChunkingConfigResponse {
     /// Maximum characters per chunk
     pub max_characters: usize,
@@ -280,5 +325,6 @@ pub struct ChunkingConfigResponse {
     /// Whether whitespace was trimmed
     pub trim: bool,
     /// Type of chunker used
+    #[cfg_attr(feature = "api", schema(example = "text"))]
     pub chunker_type: String,
 }

data/vendor/kreuzberg/src/core/config/processing.rs

@@ -84,7 +84,8 @@ pub struct ChunkingConfig {
 /// Requires the `embeddings` feature to be enabled.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct EmbeddingConfig {
-    /// The embedding model to use
+    /// The embedding model to use (defaults to "balanced" preset if not specified)
+    #[serde(default = "default_model")]
     pub model: EmbeddingModelType,
 
     /// Whether to normalize embedding vectors (recommended for cosine similarity)
@@ -156,6 +157,12 @@ fn default_batch_size() -> usize {
     32
 }
 
+fn default_model() -> EmbeddingModelType {
+    EmbeddingModelType::Preset {
+        name: "balanced".to_string(),
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;