kreuzberg 4.2.0 → 4.2.2

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

@@ -8,13 +8,60 @@ use axum::{
 use crate::{batch_extract_bytes, cache, extract_bytes};
 
 use super::{
-    error::ApiError,
+    error::{ApiError, JsonApi},
     types::{
         ApiState, CacheClearResponse, CacheStatsResponse, ChunkRequest, ChunkResponse, EmbedRequest, EmbedResponse,
         ExtractResponse, HealthResponse, InfoResponse,
     },
 };
 
+/// Health check endpoint handler.
+///
+/// GET /health
+#[utoipa::path(
+    get,
+    path = "/health",
+    tag = "health",
+    responses(
+        (status = 200, description = "Service is healthy", body = HealthResponse),
+    )
+)]
+#[cfg_attr(feature = "otel", tracing::instrument(name = "api.health"))]
+pub async fn health_handler() -> Json<HealthResponse> {
+    // Get plugin status
+    let plugin_status = crate::plugins::startup_validation::PluginHealthStatus::check();
+
+    Json(HealthResponse {
+        status: "healthy".to_string(),
+        version: env!("CARGO_PKG_VERSION").to_string(),
+        plugins: Some(super::types::PluginStatus {
+            ocr_backends_count: plugin_status.ocr_backends_count,
+            ocr_backends: plugin_status.ocr_backends,
+            extractors_count: plugin_status.extractors_count,
+            post_processors_count: plugin_status.post_processors_count,
+        }),
+    })
+}
+
+/// Server info endpoint handler.
+///
+/// GET /info
+#[utoipa::path(
+    get,
+    path = "/info",
+    tag = "health",
+    responses(
+        (status = 200, description = "Server information", body = InfoResponse),
+    )
+)]
+#[cfg_attr(feature = "otel", tracing::instrument(name = "api.info"))]
+pub async fn info_handler() -> Json<InfoResponse> {
+    Json(InfoResponse {
+        version: env!("CARGO_PKG_VERSION").to_string(),
+        rust_backend: true,
+    })
+}
+
 /// Extract endpoint handler.
 ///
 /// POST /extract
@@ -37,6 +84,19 @@ use super::{
 ///
 /// The server's default config (loaded from kreuzberg.toml/yaml/json via discovery)
 /// is used as the base, and any per-request config overrides those defaults.
+// TODO: Add utoipa::path annotation once ExtractionResult implements ToSchema
+// #[utoipa::path(
+//     post,
+//     path = "/extract",
+//     tag = "extraction",
+//     request_body(content_type = "multipart/form-data"),
+//     responses(
+//         (status = 200, description = "Extraction successful", body = ExtractResponse),
+//         (status = 400, description = "Bad request", body = crate::api::types::ErrorResponse),
+//         (status = 413, description = "Payload too large", body = crate::api::types::ErrorResponse),
+//         (status = 500, description = "Internal server error", body = crate::api::types::ErrorResponse),
+//     )
+// )]
 #[cfg_attr(
     feature = "otel",
     tracing::instrument(
@@ -132,28 +192,6 @@ pub async fn extract_handler(
     Ok(Json(results))
 }
 
-/// Health check endpoint handler.
-///
-/// GET /health
-#[cfg_attr(feature = "otel", tracing::instrument(name = "api.health"))]
-pub async fn health_handler() -> Json<HealthResponse> {
-    Json(HealthResponse {
-        status: "healthy".to_string(),
-        version: env!("CARGO_PKG_VERSION").to_string(),
-    })
-}
-
-/// Server info endpoint handler.
-///
-/// GET /info
-#[cfg_attr(feature = "otel", tracing::instrument(name = "api.info"))]
-pub async fn info_handler() -> Json<InfoResponse> {
-    Json(InfoResponse {
-        version: env!("CARGO_PKG_VERSION").to_string(),
-        rust_backend: true,
-    })
-}
-
 /// Cache stats endpoint handler.
 ///
 /// GET /cache/stats
@@ -164,6 +202,15 @@ pub async fn info_handler() -> Json<InfoResponse> {
 /// - Current directory cannot be determined
 /// - Cache directory path contains non-UTF8 characters
 /// - Cache metadata retrieval fails
+#[utoipa::path(
+    get,
+    path = "/cache/stats",
+    tag = "cache",
+    responses(
+        (status = 200, description = "Cache statistics", body = CacheStatsResponse),
+        (status = 500, description = "Internal server error", body = crate::api::types::ErrorResponse),
+    )
+)]
 #[cfg_attr(feature = "otel", tracing::instrument(name = "api.cache_stats"))]
 pub async fn cache_stats_handler() -> Result<Json<CacheStatsResponse>, ApiError> {
     let cache_dir = std::env::current_dir()
@@ -204,6 +251,15 @@ pub async fn cache_stats_handler() -> Result<Json<CacheStatsResponse>, ApiError>
 /// - Current directory cannot be determined
 /// - Cache directory path contains non-UTF8 characters
 /// - Cache clearing operation fails
+#[utoipa::path(
+    delete,
+    path = "/cache/clear",
+    tag = "cache",
+    responses(
+        (status = 200, description = "Cache cleared", body = CacheClearResponse),
+        (status = 500, description = "Internal server error", body = crate::api::types::ErrorResponse),
+    )
+)]
 #[cfg_attr(feature = "otel", tracing::instrument(name = "api.cache_clear"))]
 pub async fn cache_clear_handler() -> Result<Json<CacheClearResponse>, ApiError> {
     let cache_dir = std::env::current_dir()
@@ -248,6 +304,18 @@ pub async fn cache_clear_handler() -> Result<Json<CacheClearResponse>, ApiError>
 /// - ONNX Runtime is not available
 /// - Model initialization fails
 /// - Embedding generation fails
+#[utoipa::path(
+    post,
+    path = "/embed",
+    tag = "embeddings",
+    request_body = EmbedRequest,
+    responses(
+        (status = 200, description = "Embeddings generated", body = EmbedResponse),
+        (status = 400, description = "Bad request - validation failed (e.g., empty texts array)", body = crate::api::types::ErrorResponse),
+        (status = 422, description = "Unprocessable entity - invalid JSON body", body = crate::api::types::ErrorResponse),
+        (status = 500, description = "Internal server error", body = crate::api::types::ErrorResponse),
+    )
+)]
 #[cfg(feature = "embeddings")]
 #[cfg_attr(
     feature = "otel",
@@ -260,7 +328,7 @@ pub async fn cache_clear_handler() -> Result<Json<CacheClearResponse>, ApiError>
         )
     )
 )]
-pub async fn embed_handler(Json(request): Json<EmbedRequest>) -> Result<Json<EmbedResponse>, ApiError> {
+pub async fn embed_handler(JsonApi(request): JsonApi<EmbedRequest>) -> Result<Json<EmbedResponse>, ApiError> {
     use crate::types::{Chunk, ChunkMetadata};
 
     if request.texts.is_empty() {
@@ -269,6 +337,13 @@ pub async fn embed_handler(Json(request): Json<EmbedRequest>) -> Result<Json<Emb
         )));
     }
 
+    // Validate that no texts are empty
+    if request.texts.iter().any(|t| t.is_empty()) {
+        return Err(ApiError::validation(crate::error::KreuzbergError::validation(
+            "All text entries must be non-empty strings",
+        )));
+    }
+
     // Use default config if none provided
     let config = request.config.unwrap_or_default();
 
@@ -331,8 +406,20 @@ pub async fn embed_handler(Json(request): Json<EmbedRequest>) -> Result<Json<Emb
 /// Embedding endpoint handler (when embeddings feature is disabled).
 ///
 /// Returns an error indicating embeddings feature is not enabled.
+#[utoipa::path(
+    post,
+    path = "/embed",
+    tag = "embeddings",
+    request_body = EmbedRequest,
+    responses(
+        (status = 200, description = "Embeddings generated", body = EmbedResponse),
+        (status = 400, description = "Bad request - validation failed (e.g., empty texts array)", body = crate::api::types::ErrorResponse),
+        (status = 422, description = "Unprocessable entity - invalid JSON body", body = crate::api::types::ErrorResponse),
+        (status = 500, description = "Internal server error", body = crate::api::types::ErrorResponse),
+    )
+)]
 #[cfg(not(feature = "embeddings"))]
-pub async fn embed_handler(Json(_request): Json<EmbedRequest>) -> Result<Json<EmbedResponse>, ApiError> {
+pub async fn embed_handler(JsonApi(_request): JsonApi<EmbedRequest>) -> Result<Json<EmbedResponse>, ApiError> {
     Err(ApiError::internal(crate::error::KreuzbergError::MissingDependency(
         "Embeddings feature is not enabled. Rebuild with --features embeddings".to_string(),
     )))
@@ -344,6 +431,18 @@ pub async fn embed_handler(Json(_request): Json<EmbedRequest>) -> Result<Json<Em
 ///
 /// Accepts JSON body with text and optional configuration.
 /// Returns chunks with metadata.
+#[utoipa::path(
+    post,
+    path = "/chunk",
+    tag = "chunking",
+    request_body = ChunkRequest,
+    responses(
+        (status = 200, description = "Text chunked successfully", body = ChunkResponse),
+        (status = 400, description = "Bad request - validation failed (e.g., empty text)", body = crate::api::types::ErrorResponse),
+        (status = 422, description = "Unprocessable entity - invalid JSON body", body = crate::api::types::ErrorResponse),
+        (status = 500, description = "Internal server error", body = crate::api::types::ErrorResponse),
+    )
+)]
 #[cfg_attr(
     feature = "otel",
     tracing::instrument(
@@ -352,7 +451,7 @@ pub async fn embed_handler(Json(_request): Json<EmbedRequest>) -> Result<Json<Em
         fields(text_length = request.text.len(), chunker_type = request.chunker_type.as_str())
     )
 )]
-pub async fn chunk_handler(Json(request): Json<ChunkRequest>) -> Result<Json<ChunkResponse>, ApiError> {
+pub async fn chunk_handler(JsonApi(request): JsonApi<ChunkRequest>) -> Result<Json<ChunkResponse>, ApiError> {
     use super::types::{ChunkItem, ChunkingConfigResponse};
     use crate::chunking::{ChunkerType, ChunkingConfig, chunk_text};
 
@@ -363,9 +462,9 @@ pub async fn chunk_handler(Json(request): Json<ChunkRequest>) -> Result<Json<Chu
         )));
     }
 
-    // Parse chunker_type
+    // Parse chunker_type (empty string is invalid, use default by omitting the field)
     let chunker_type = match request.chunker_type.to_lowercase().as_str() {
-        "text" | "" => ChunkerType::Text,
+        "text" => ChunkerType::Text,
         "markdown" => ChunkerType::Markdown,
         other => {
             return Err(ApiError::validation(crate::error::KreuzbergError::validation(format!(
@@ -377,15 +476,37 @@ pub async fn chunk_handler(Json(request): Json<ChunkRequest>) -> Result<Json<Chu
 
     // Build config with defaults
     let cfg = request.config.unwrap_or_default();
+    let max_characters = cfg.max_characters.unwrap_or(2000);
+    let overlap = cfg.overlap.unwrap_or(100);
+
+    // Validate chunking configuration
+    if overlap >= max_characters {
+        return Err(ApiError::validation(crate::error::KreuzbergError::validation(format!(
+            "Invalid chunking configuration: overlap ({}) must be less than max_characters ({})",
+            overlap, max_characters
+        ))));
+    }
+
     let config = ChunkingConfig {
-        max_characters: cfg.max_characters.unwrap_or(2000),
-        overlap: cfg.overlap.unwrap_or(100),
+        max_characters,
+        overlap,
         trim: cfg.trim.unwrap_or(true),
         chunker_type,
     };
 
-    // Perform chunking
-    let result = chunk_text(&request.text, &config, None).map_err(ApiError::internal)?;
+    // Perform chunking - convert any remaining errors to validation errors since they're likely config issues
+    let result = chunk_text(&request.text, &config, None).map_err(|e| {
+        // Check if error message indicates a configuration issue
+        let msg = e.to_string();
+        if msg.contains("configuration") || msg.contains("overlap") || msg.contains("capacity") {
+            ApiError::validation(crate::error::KreuzbergError::validation(format!(
+                "Invalid chunking configuration: {}",
+                msg
+            )))
+        } else {
+            ApiError::internal(e)
+        }
+    })?;
 
     // Transform to response
     let chunks = result

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

@@ -87,6 +87,8 @@
 mod config;
 mod error;
 mod handlers;
+#[cfg(feature = "api")]
+pub mod openapi;
 mod router;
 mod startup;
 mod types;

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};
+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,6 +82,10 @@ pub async fn serve(host: impl AsRef<str>, port: u16) -> Result<()> {
         server_config.max_multipart_field_bytes,
     );
 
+    // 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
 }
 
@@ -111,6 +117,11 @@ pub async fn serve_with_config(host: impl AsRef<str>, port: u16, config: Extract
         "Upload size limit: 100 MB (default, {} bytes)",
         limits.max_request_body_bytes
     );
+
+    // Initialize extractors and validate plugins at startup
+    extractors::ensure_initialized()?;
+    validate_plugins_at_startup()?;
+
     serve_with_config_and_limits(host, port, config, limits).await
 }
 
@@ -158,6 +169,10 @@ 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);
 
+    // Initialize extractors and validate plugins at startup
+    extractors::ensure_initialized()?;
+    validate_plugins_at_startup()?;
+
     tracing::info!("Starting Kreuzberg API server on http://{}:{}", ip, port);
 
     let listener = tokio::net::TcpListener::bind(addr)
@@ -214,6 +229,10 @@ 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());
 
+    // Initialize extractors and validate plugins at startup
+    extractors::ensure_initialized()?;
+    validate_plugins_at_startup()?;
+
     tracing::info!(
         "Starting Kreuzberg API server on http://{}:{} (request_body_limit={} MB, multipart_field_limit={} MB)",
         ip,
@@ -238,6 +257,7 @@ pub async fn serve_with_server_config(extraction_config: ExtractionConfig, serve
 /// Defaults: host = "127.0.0.1", port = 8000
 ///
 /// Uses config file discovery (searches current/parent directories for kreuzberg.toml/yaml/json).
+/// Validates plugins at startup to help diagnose configuration issues.
 pub async fn serve_default() -> Result<()> {
     serve("127.0.0.1", 8000).await
 }