fix: add extract_annotations and margin config to all bindings

- Go/Java/C#/Python/Node/WASM/Ruby/PHP: add extract_annotations,
  top_margin_fraction, bottom_margin_fraction to PdfConfig
- Python .pyi stubs: add new fields and constructor params
- Ruby: add PdfAnnotation type, annotations to Result, config fields
- PHP: add PdfAnnotation type class, annotations to ExtractionResult
- TypeScript: update core types, WASM types, test-utils config mapping
- WASM Deno: fix missing initWasm() in plugin-api test generator
- WASM: make unregisterOcrBackend graceful (no-throw on missing)
- Regenerate wasm-deno e2e tests

Author: Goldziher

crates/kreuzberg-node/src/config/types.rs

@@ -322,6 +322,9 @@ pub struct JsPdfConfig {
     pub passwords: Option<Vec<String>>,
     pub extract_metadata: Option<bool>,
     pub hierarchy: Option<JsHierarchyConfig>,
+    pub extract_annotations: Option<bool>,
+    pub top_margin_fraction: Option<f64>,
+    pub bottom_margin_fraction: Option<f64>,
 }
 
 impl From<JsPdfConfig> for RustPdfConfig {
@@ -331,9 +334,9 @@ impl From<JsPdfConfig> for RustPdfConfig {
             passwords: val.passwords,
             extract_metadata: val.extract_metadata.unwrap_or(true),
             hierarchy: val.hierarchy.map(|h| h.into()),
-            extract_annotations: false,
-            top_margin_fraction: None,
-            bottom_margin_fraction: None,
+            extract_annotations: val.extract_annotations.unwrap_or(false),
+            top_margin_fraction: val.top_margin_fraction.map(|v| v as f32),
+            bottom_margin_fraction: val.bottom_margin_fraction.map(|v| v as f32),
         }
     }
 }
@@ -1128,6 +1131,9 @@ impl TryFrom<ExtractionConfig> for JsExtractionConfig {
                     include_bbox: Some(h.include_bbox),
                     ocr_coverage_threshold: h.ocr_coverage_threshold.map(|v| v as f64),
                 }),
+                extract_annotations: Some(pdf.extract_annotations),
+                top_margin_fraction: pdf.top_margin_fraction.map(|v| v as f64),
+                bottom_margin_fraction: pdf.bottom_margin_fraction.map(|v| v as f64),
             }),
             token_reduction: val.token_reduction.map(|tr| JsTokenReductionConfig {
                 mode: Some(tr.mode),

crates/kreuzberg-node/typescript/types.ts

@@ -318,6 +318,15 @@ export interface PdfConfig {
 
 	/** Hierarchy extraction configuration. */
 	hierarchy?: HierarchyConfig;
+
+	/** Extract annotations from PDF pages. Default: false. */
+	extractAnnotations?: boolean;
+
+	/** Top margin fraction (0.0-0.5) for filtering header content. */
+	topMarginFraction?: number;
+
+	/** Bottom margin fraction (0.0-0.5) for filtering footer content. */
+	bottomMarginFraction?: number;
 }
 
 /**

crates/kreuzberg-py/src/config/types.rs

@@ -878,22 +878,25 @@ pub struct PdfConfig {
 #[pymethods]
 impl PdfConfig {
     #[new]
-    #[pyo3(signature = (extract_images=None, passwords=None, extract_metadata=None, hierarchy=None))]
+    #[pyo3(signature = (extract_images=None, passwords=None, extract_metadata=None, hierarchy=None, extract_annotations=None, top_margin_fraction=None, bottom_margin_fraction=None))]
     fn new(
         extract_images: Option<bool>,
         passwords: Option<Vec<String>>,
         extract_metadata: Option<bool>,
         hierarchy: Option<HierarchyConfig>,
+        extract_annotations: Option<bool>,
+        top_margin_fraction: Option<f32>,
+        bottom_margin_fraction: Option<f32>,
     ) -> Self {
         Self {
             inner: kreuzberg::PdfConfig {
                 extract_images: extract_images.unwrap_or(false),
                 passwords,
                 extract_metadata: extract_metadata.unwrap_or(true),
                 hierarchy: hierarchy.map(|h| h.inner),
-                extract_annotations: false,
-                top_margin_fraction: None,
-                bottom_margin_fraction: None,
+                extract_annotations: extract_annotations.unwrap_or(false),
+                top_margin_fraction,
+                bottom_margin_fraction,
             },
         }
     }
@@ -938,6 +941,36 @@ impl PdfConfig {
         self.inner.hierarchy = value.map(|h| h.inner);
     }
 
+    #[getter]
+    fn extract_annotations(&self) -> bool {
+        self.inner.extract_annotations
+    }
+
+    #[setter]
+    fn set_extract_annotations(&mut self, value: bool) {
+        self.inner.extract_annotations = value;
+    }
+
+    #[getter]
+    fn top_margin_fraction(&self) -> Option<f32> {
+        self.inner.top_margin_fraction
+    }
+
+    #[setter]
+    fn set_top_margin_fraction(&mut self, value: Option<f32>) {
+        self.inner.top_margin_fraction = value;
+    }
+
+    #[getter]
+    fn bottom_margin_fraction(&self) -> Option<f32> {
+        self.inner.bottom_margin_fraction
+    }
+
+    #[setter]
+    fn set_bottom_margin_fraction(&mut self, value: Option<f32>) {
+        self.inner.bottom_margin_fraction = value;
+    }
+
     fn __repr__(&self) -> String {
         format!(
             "PdfConfig(extract_images={}, extract_metadata={}, passwords={})",

crates/kreuzberg-wasm/typescript/ocr/registry.spec.ts

@@ -215,8 +215,8 @@ describe("OCR Registry", () => {
 			expect(getOcrBackend("test")).toBeUndefined();
 		});
 
-		it("should throw if backend not found", async () => {
-			await expect(unregisterOcrBackend("nonexistent")).rejects.toThrow('OCR backend "nonexistent" is not registered');
+		it("should silently succeed if backend not found", async () => {
+			await unregisterOcrBackend("nonexistent");
 		});
 
 		it("should call shutdown method if available", async () => {
@@ -258,22 +258,18 @@ describe("OCR Registry", () => {
 			const backend = createMockBackend("Test");
 			registerOcrBackend(backend);
 
-			await expect(unregisterOcrBackend("test")).rejects.toThrow("is not registered");
+			await unregisterOcrBackend("test");
 
 			expect(getOcrBackend("Test")).toBe(backend);
 		});
 
-		it("should throw error that lists available backends", async () => {
+		it("should silently succeed when unregistering nonexistent with others registered", async () => {
 			const backend = createMockBackend("available");
 			registerOcrBackend(backend);
 
-			try {
-				await unregisterOcrBackend("nonexistent");
-			} catch (error) {
-				if (error instanceof Error) {
-					expect(error.message).toContain("available");
-				}
-			}
+			await unregisterOcrBackend("nonexistent");
+
+			expect(getOcrBackend("available")).toBe(backend);
 		});
 	});
 

crates/kreuzberg-wasm/typescript/ocr/registry.ts

@@ -125,9 +125,7 @@ export async function unregisterOcrBackend(name: string): Promise<void> {
 	const backend = ocrBackendRegistry.get(name);
 
 	if (!backend) {
-		throw new Error(
-			`OCR backend "${name}" is not registered. Available backends: ${Array.from(ocrBackendRegistry.keys()).join(", ")}`,
-		);
+		return;
 	}
 
 	if (typeof backend.shutdown === "function") {

crates/kreuzberg-wasm/typescript/types.ts

@@ -302,6 +302,12 @@ export interface PdfConfig {
 	passwords?: string[];
 	/** Whether to extract metadata */
 	extractMetadata?: boolean;
+	/** Whether to extract annotations from PDF */
+	extractAnnotations?: boolean;
+	/** Top margin fraction (0.0-0.5) for filtering header content */
+	topMarginFraction?: number;
+	/** Bottom margin fraction (0.0-0.5) for filtering footer content */
+	bottomMarginFraction?: number;
 }
 
 /**

e2e/wasm-deno/plugin-apis.test.ts

@@ -13,13 +13,16 @@ import {
 	clearValidators,
 	detectMimeFromBytes,
 	getExtensionsForMime,
+	initWasm,
 	listOcrBackends,
 	listPostProcessors,
 	listValidators,
 	unregisterOcrBackend,
 } from "npm:@kreuzberg/wasm@^4.0.0";
 import { assertEquals } from "@std/assert";
 
+await initWasm();
+
 // Configuration
 
 Deno.test({ name: "Discover configuration from current or parent directories", ignore: true, fn() {} });

packages/csharp/Kreuzberg/Models.cs

@@ -2485,6 +2485,24 @@ public sealed class PdfConfig
     /// </summary>
     [JsonPropertyName("hierarchy")]
     public HierarchyConfig? Hierarchy { get; init; }
+
+    /// <summary>
+    /// Whether to extract annotations from PDF documents.
+    /// </summary>
+    [JsonPropertyName("extract_annotations")]
+    public bool? ExtractAnnotations { get; init; }
+
+    /// <summary>
+    /// Top margin fraction (0.0-0.5) for filtering header content.
+    /// </summary>
+    [JsonPropertyName("top_margin_fraction")]
+    public float? TopMarginFraction { get; init; }
+
+    /// <summary>
+    /// Bottom margin fraction (0.0-0.5) for filtering footer content.
+    /// </summary>
+    [JsonPropertyName("bottom_margin_fraction")]
+    public float? BottomMarginFraction { get; init; }
 }
 
 /// <summary>

packages/go/v4/config_types.go

@@ -199,10 +199,13 @@ type FontConfig struct {
 
 // PdfConfig exposes PDF-specific options.
 type PdfConfig struct {
-	ExtractImages   *bool       `json:"extract_images,omitempty"`
-	Passwords       []string    `json:"passwords,omitempty"`
-	ExtractMetadata *bool       `json:"extract_metadata,omitempty"`
-	FontConfig      *FontConfig `json:"font_config,omitempty"`
+	ExtractImages        *bool       `json:"extract_images,omitempty"`
+	Passwords            []string    `json:"passwords,omitempty"`
+	ExtractMetadata      *bool       `json:"extract_metadata,omitempty"`
+	FontConfig           *FontConfig `json:"font_config,omitempty"`
+	ExtractAnnotations   *bool       `json:"extract_annotations,omitempty"`
+	TopMarginFraction    *float64    `json:"top_margin_fraction,omitempty"`
+	BottomMarginFraction *float64    `json:"bottom_margin_fraction,omitempty"`
 }
 
 // HierarchyConfig controls PDF hierarchy extraction based on font sizes.

packages/java/src/main/java/dev/kreuzberg/config/PdfConfig.java

@@ -17,6 +17,9 @@ public final class PdfConfig {
 	private final boolean extractMetadata;
 	private final FontConfig fontConfig;
 	private final HierarchyConfig hierarchyConfig;
+	private final boolean extractAnnotations;
+	private final Double topMarginFraction;
+	private final Double bottomMarginFraction;
 
 	private PdfConfig(Builder builder) {
 		this.extractImages = builder.extractImages;
@@ -26,6 +29,9 @@ private PdfConfig(Builder builder) {
 		this.extractMetadata = builder.extractMetadata;
 		this.fontConfig = builder.fontConfig;
 		this.hierarchyConfig = builder.hierarchyConfig;
+		this.extractAnnotations = builder.extractAnnotations;
+		this.topMarginFraction = builder.topMarginFraction;
+		this.bottomMarginFraction = builder.bottomMarginFraction;
 	}
 
 	public static Builder builder() {
@@ -52,19 +58,38 @@ public HierarchyConfig getHierarchyConfig() {
 		return hierarchyConfig;
 	}
 
+	public boolean isExtractAnnotations() {
+		return extractAnnotations;
+	}
+
+	public Double getTopMarginFraction() {
+		return topMarginFraction;
+	}
+
+	public Double getBottomMarginFraction() {
+		return bottomMarginFraction;
+	}
+
 	public Map<String, Object> toMap() {
 		Map<String, Object> map = new HashMap<>();
 		map.put("extract_images", extractImages);
 		if (passwords != null && !passwords.isEmpty()) {
 			map.put("passwords", passwords);
 		}
 		map.put("extract_metadata", extractMetadata);
+		map.put("extract_annotations", extractAnnotations);
 		if (fontConfig != null) {
 			map.put("font_config", fontConfig.toMap());
 		}
 		if (hierarchyConfig != null) {
 			map.put("hierarchy", hierarchyConfig.toMap());
 		}
+		if (topMarginFraction != null) {
+			map.put("top_margin_fraction", topMarginFraction);
+		}
+		if (bottomMarginFraction != null) {
+			map.put("bottom_margin_fraction", bottomMarginFraction);
+		}
 		return map;
 	}
 
@@ -74,6 +99,9 @@ public static final class Builder {
 		private boolean extractMetadata = true;
 		private FontConfig fontConfig;
 		private HierarchyConfig hierarchyConfig;
+		private boolean extractAnnotations = false;
+		private Double topMarginFraction;
+		private Double bottomMarginFraction;
 
 		private Builder() {
 		}
@@ -111,6 +139,21 @@ public Builder hierarchyConfig(HierarchyConfig hierarchyConfig) {
 			return this;
 		}
 
+		public Builder extractAnnotations(boolean extractAnnotations) {
+			this.extractAnnotations = extractAnnotations;
+			return this;
+		}
+
+		public Builder topMarginFraction(Double topMarginFraction) {
+			this.topMarginFraction = topMarginFraction;
+			return this;
+		}
+
+		public Builder bottomMarginFraction(Double bottomMarginFraction) {
+			this.bottomMarginFraction = bottomMarginFraction;
+			return this;
+		}
+
 		public PdfConfig build() {
 			return new PdfConfig(this);
 		}
@@ -141,6 +184,18 @@ static PdfConfig fromMap(Map<String, Object> map) {
 		if (extractMetadataValue instanceof Boolean) {
 			builder.extractMetadata((Boolean) extractMetadataValue);
 		}
+		Object extractAnnotationsValue = map.get("extract_annotations");
+		if (extractAnnotationsValue instanceof Boolean) {
+			builder.extractAnnotations((Boolean) extractAnnotationsValue);
+		}
+		Object topMarginValue = map.get("top_margin_fraction");
+		if (topMarginValue instanceof Number) {
+			builder.topMarginFraction(((Number) topMarginValue).doubleValue());
+		}
+		Object bottomMarginValue = map.get("bottom_margin_fraction");
+		if (bottomMarginValue instanceof Number) {
+			builder.bottomMarginFraction(((Number) bottomMarginValue).doubleValue());
+		}
 		@SuppressWarnings("unchecked")
 		Map<String, Object> fontConfigMap = map.get("font_config") instanceof Map
 				? (Map<String, Object>) map.get("font_config")