@kreuzberg/wasm 4.0.0-rc.10

package/dist/ocr/tesseract-wasm-backend.d.cts

@@ -0,0 +1,257 @@
+import { O as OcrBackendProtocol } from '../types-CKjcIYcX.cjs';
+
+/**
+ * Tesseract WASM OCR Backend
+ *
+ * Provides OCR capabilities using tesseract-wasm library for browser environments.
+ * Loads training data on-demand from jsDelivr CDN and implements the OcrBackendProtocol.
+ *
+ * ## Browser-Only Requirement
+ *
+ * This backend requires browser APIs like createImageBitmap and Web Workers.
+ * It will NOT work in Node.js environments without additional canvas polyfills.
+ *
+ * ## Supported Languages
+ *
+ * Common ISO 639-1 and ISO 639-2 codes:
+ * - English: "eng"
+ * - German: "deu"
+ * - French: "fra"
+ * - Spanish: "spa"
+ * - Italian: "ita"
+ * - Portuguese: "por"
+ * - Dutch: "nld"
+ * - Russian: "rus"
+ * - Chinese (Simplified): "chi_sim"
+ * - Chinese (Traditional): "chi_tra"
+ * - Japanese: "jpn"
+ * - Korean: "kor"
+ * - Arabic: "ara"
+ * - Hindi: "hin"
+ *
+ * For complete language list, see: https://github.com/naptha/tesseract.js
+ *
+ * @example Basic Usage
+ * ```typescript
+ * import { TesseractWasmBackend } from '@kreuzberg/wasm/ocr/tesseract-wasm-backend';
+ * import { registerOcrBackend, extractBytes, initWasm } from '@kreuzberg/wasm';
+ *
+ * // Initialize
+ * await initWasm();
+ * const backend = new TesseractWasmBackend();
+ * await backend.initialize();
+ * registerOcrBackend(backend);
+ *
+ * // Use in extraction
+ * const imageBytes = new Uint8Array(buffer);
+ * const result = await extractBytes(imageBytes, 'image/png', {
+ *   ocr: { backend: 'tesseract-wasm', language: 'eng' }
+ * });
+ * console.log(result.content); // Extracted text
+ * ```
+ *
+ * @example With Language Auto-Detection
+ * ```typescript
+ * const backend = new TesseractWasmBackend();
+ * await backend.initialize();
+ * registerOcrBackend(backend);
+ *
+ * // Extract without specifying language - backend will auto-detect
+ * const result = await extractBytes(imageBytes, 'image/png', {
+ *   ocr: { backend: 'tesseract-wasm' } // language will auto-detect
+ * });
+ * ```
+ */
+
+/**
+ * TesseractWasmBackend - OCR backend using tesseract-wasm library
+ *
+ * Implements the OcrBackendProtocol for Kreuzberg document extraction pipeline.
+ * Provides comprehensive OCR support with model caching, error handling, and progress reporting.
+ */
+declare class TesseractWasmBackend implements OcrBackendProtocol {
+    /** Tesseract WASM client instance */
+    private client;
+    /** Track which models are currently loaded to avoid redundant loads */
+    private loadedLanguages;
+    /** Cache for language availability validation */
+    private supportedLangsCache;
+    /** Progress callback for UI updates */
+    private progressCallback;
+    /** Base URL for training data CDN */
+    private readonly CDN_BASE_URL;
+    /**
+     * Return the unique name of this OCR backend
+     *
+     * @returns Backend identifier "tesseract-wasm"
+     */
+    name(): string;
+    /**
+     * Return list of supported language codes
+     *
+     * Returns a curated list of commonly available Tesseract language models.
+     * Tesseract supports many more languages through custom models.
+     *
+     * @returns Array of ISO 639-1/2/3 language codes
+     */
+    supportedLanguages(): string[];
+    /**
+     * Initialize the OCR backend
+     *
+     * Creates the Tesseract WASM client instance. This is called once when
+     * the backend is registered with the extraction pipeline.
+     *
+     * The actual model loading happens in processImage() on-demand to avoid
+     * loading all models upfront.
+     *
+     * @throws {Error} If tesseract-wasm is not available or initialization fails
+     *
+     * @example
+     * ```typescript
+     * const backend = new TesseractWasmBackend();
+     * try {
+     *   await backend.initialize();
+     * } catch (error) {
+     *   console.error('Failed to initialize OCR:', error);
+     * }
+     * ```
+     */
+    initialize(): Promise<void>;
+    /**
+     * Process image bytes and extract text via OCR
+     *
+     * Handles image loading, model loading, OCR processing, and result formatting.
+     * Automatically loads the language model on first use and caches it for subsequent calls.
+     *
+     * @param imageBytes - Raw image data (Uint8Array) or Base64-encoded string
+     * @param language - ISO 639-2/3 language code (e.g., "eng", "deu")
+     * @returns Promise resolving to OCR result with content and metadata
+     * @throws {Error} If image processing fails, model loading fails, or language is unsupported
+     *
+     * @example
+     * ```typescript
+     * const backend = new TesseractWasmBackend();
+     * await backend.initialize();
+     *
+     * const imageBuffer = fs.readFileSync('scanned.png');
+     * const result = await backend.processImage(
+     *   new Uint8Array(imageBuffer),
+     *   'eng'
+     * );
+     *
+     * console.log(result.content); // Extracted text
+     * console.log(result.metadata.confidence); // OCR confidence score
+     * ```
+     */
+    processImage(imageBytes: Uint8Array | string, language: string): Promise<{
+        content: string;
+        mime_type: string;
+        metadata: Record<string, unknown>;
+        tables: unknown[];
+    }>;
+    /**
+     * Shutdown the OCR backend and release resources
+     *
+     * Properly cleans up the Tesseract WASM client, freeing memory and Web Workers.
+     * Called when the backend is unregistered or the application shuts down.
+     *
+     * @throws {Error} If cleanup fails (errors are logged but not critical)
+     *
+     * @example
+     * ```typescript
+     * const backend = new TesseractWasmBackend();
+     * await backend.initialize();
+     * // ... use backend ...
+     * await backend.shutdown(); // Clean up resources
+     * ```
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Set a progress callback for UI updates
+     *
+     * Allows the UI to display progress during OCR processing.
+     * The callback will be called with values from 0 to 100.
+     *
+     * @param callback - Function to call with progress percentage
+     *
+     * @example
+     * ```typescript
+     * const backend = new TesseractWasmBackend();
+     * backend.setProgressCallback((progress) => {
+     *   console.log(`OCR Progress: ${progress}%`);
+     *   document.getElementById('progress-bar').style.width = `${progress}%`;
+     * });
+     * ```
+     */
+    setProgressCallback(callback: (progress: number) => void): void;
+    /**
+     * Load language model from CDN
+     *
+     * Fetches the training data for a specific language from jsDelivr CDN.
+     * This is an MVP approach - models are cached by the browser.
+     *
+     * @param language - ISO 639-2/3 language code
+     * @throws {Error} If model download fails or language is not available
+     *
+     * @internal
+     */
+    private loadLanguageModel;
+    /**
+     * Convert image bytes or Base64 string to ImageBitmap
+     *
+     * Handles both Uint8Array and Base64-encoded image data, converting to
+     * ImageBitmap format required by Tesseract WASM.
+     *
+     * @param imageBytes - Image data as Uint8Array or Base64 string
+     * @returns Promise resolving to ImageBitmap
+     * @throws {Error} If conversion fails (browser API not available or invalid image data)
+     *
+     * @internal
+     */
+    private convertToImageBitmap;
+    /**
+     * Get confidence score from OCR result
+     *
+     * Attempts to retrieve confidence score from Tesseract.
+     * Returns a safe default if unavailable.
+     *
+     * @returns Confidence score between 0 and 1
+     *
+     * @internal
+     */
+    private getConfidenceScore;
+    /**
+     * Get page metadata from OCR result
+     *
+     * Retrieves additional metadata like image dimensions and processing info.
+     *
+     * @returns Metadata object (may be empty if unavailable)
+     *
+     * @internal
+     */
+    private getPageMetadata;
+    /**
+     * Dynamically load tesseract-wasm module
+     *
+     * Uses dynamic import to load tesseract-wasm only when needed,
+     * avoiding hard dependency in browser environments where it may not be bundled.
+     *
+     * @returns tesseract-wasm module object
+     * @throws {Error} If module cannot be imported
+     *
+     * @internal
+     */
+    private loadTesseractWasm;
+    /**
+     * Report progress to progress callback
+     *
+     * Internal helper for notifying progress updates during OCR processing.
+     *
+     * @param progress - Progress percentage (0-100)
+     *
+     * @internal
+     */
+    private reportProgress;
+}
+
+export { TesseractWasmBackend };

package/dist/ocr/tesseract-wasm-backend.d.ts

@@ -0,0 +1,257 @@
+import { O as OcrBackendProtocol } from '../types-CKjcIYcX.js';
+
+/**
+ * Tesseract WASM OCR Backend
+ *
+ * Provides OCR capabilities using tesseract-wasm library for browser environments.
+ * Loads training data on-demand from jsDelivr CDN and implements the OcrBackendProtocol.
+ *
+ * ## Browser-Only Requirement
+ *
+ * This backend requires browser APIs like createImageBitmap and Web Workers.
+ * It will NOT work in Node.js environments without additional canvas polyfills.
+ *
+ * ## Supported Languages
+ *
+ * Common ISO 639-1 and ISO 639-2 codes:
+ * - English: "eng"
+ * - German: "deu"
+ * - French: "fra"
+ * - Spanish: "spa"
+ * - Italian: "ita"
+ * - Portuguese: "por"
+ * - Dutch: "nld"
+ * - Russian: "rus"
+ * - Chinese (Simplified): "chi_sim"
+ * - Chinese (Traditional): "chi_tra"
+ * - Japanese: "jpn"
+ * - Korean: "kor"
+ * - Arabic: "ara"
+ * - Hindi: "hin"
+ *
+ * For complete language list, see: https://github.com/naptha/tesseract.js
+ *
+ * @example Basic Usage
+ * ```typescript
+ * import { TesseractWasmBackend } from '@kreuzberg/wasm/ocr/tesseract-wasm-backend';
+ * import { registerOcrBackend, extractBytes, initWasm } from '@kreuzberg/wasm';
+ *
+ * // Initialize
+ * await initWasm();
+ * const backend = new TesseractWasmBackend();
+ * await backend.initialize();
+ * registerOcrBackend(backend);
+ *
+ * // Use in extraction
+ * const imageBytes = new Uint8Array(buffer);
+ * const result = await extractBytes(imageBytes, 'image/png', {
+ *   ocr: { backend: 'tesseract-wasm', language: 'eng' }
+ * });
+ * console.log(result.content); // Extracted text
+ * ```
+ *
+ * @example With Language Auto-Detection
+ * ```typescript
+ * const backend = new TesseractWasmBackend();
+ * await backend.initialize();
+ * registerOcrBackend(backend);
+ *
+ * // Extract without specifying language - backend will auto-detect
+ * const result = await extractBytes(imageBytes, 'image/png', {
+ *   ocr: { backend: 'tesseract-wasm' } // language will auto-detect
+ * });
+ * ```
+ */
+
+/**
+ * TesseractWasmBackend - OCR backend using tesseract-wasm library
+ *
+ * Implements the OcrBackendProtocol for Kreuzberg document extraction pipeline.
+ * Provides comprehensive OCR support with model caching, error handling, and progress reporting.
+ */
+declare class TesseractWasmBackend implements OcrBackendProtocol {
+    /** Tesseract WASM client instance */
+    private client;
+    /** Track which models are currently loaded to avoid redundant loads */
+    private loadedLanguages;
+    /** Cache for language availability validation */
+    private supportedLangsCache;
+    /** Progress callback for UI updates */
+    private progressCallback;
+    /** Base URL for training data CDN */
+    private readonly CDN_BASE_URL;
+    /**
+     * Return the unique name of this OCR backend
+     *
+     * @returns Backend identifier "tesseract-wasm"
+     */
+    name(): string;
+    /**
+     * Return list of supported language codes
+     *
+     * Returns a curated list of commonly available Tesseract language models.
+     * Tesseract supports many more languages through custom models.
+     *
+     * @returns Array of ISO 639-1/2/3 language codes
+     */
+    supportedLanguages(): string[];
+    /**
+     * Initialize the OCR backend
+     *
+     * Creates the Tesseract WASM client instance. This is called once when
+     * the backend is registered with the extraction pipeline.
+     *
+     * The actual model loading happens in processImage() on-demand to avoid
+     * loading all models upfront.
+     *
+     * @throws {Error} If tesseract-wasm is not available or initialization fails
+     *
+     * @example
+     * ```typescript
+     * const backend = new TesseractWasmBackend();
+     * try {
+     *   await backend.initialize();
+     * } catch (error) {
+     *   console.error('Failed to initialize OCR:', error);
+     * }
+     * ```
+     */
+    initialize(): Promise<void>;
+    /**
+     * Process image bytes and extract text via OCR
+     *
+     * Handles image loading, model loading, OCR processing, and result formatting.
+     * Automatically loads the language model on first use and caches it for subsequent calls.
+     *
+     * @param imageBytes - Raw image data (Uint8Array) or Base64-encoded string
+     * @param language - ISO 639-2/3 language code (e.g., "eng", "deu")
+     * @returns Promise resolving to OCR result with content and metadata
+     * @throws {Error} If image processing fails, model loading fails, or language is unsupported
+     *
+     * @example
+     * ```typescript
+     * const backend = new TesseractWasmBackend();
+     * await backend.initialize();
+     *
+     * const imageBuffer = fs.readFileSync('scanned.png');
+     * const result = await backend.processImage(
+     *   new Uint8Array(imageBuffer),
+     *   'eng'
+     * );
+     *
+     * console.log(result.content); // Extracted text
+     * console.log(result.metadata.confidence); // OCR confidence score
+     * ```
+     */
+    processImage(imageBytes: Uint8Array | string, language: string): Promise<{
+        content: string;
+        mime_type: string;
+        metadata: Record<string, unknown>;
+        tables: unknown[];
+    }>;
+    /**
+     * Shutdown the OCR backend and release resources
+     *
+     * Properly cleans up the Tesseract WASM client, freeing memory and Web Workers.
+     * Called when the backend is unregistered or the application shuts down.
+     *
+     * @throws {Error} If cleanup fails (errors are logged but not critical)
+     *
+     * @example
+     * ```typescript
+     * const backend = new TesseractWasmBackend();
+     * await backend.initialize();
+     * // ... use backend ...
+     * await backend.shutdown(); // Clean up resources
+     * ```
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Set a progress callback for UI updates
+     *
+     * Allows the UI to display progress during OCR processing.
+     * The callback will be called with values from 0 to 100.
+     *
+     * @param callback - Function to call with progress percentage
+     *
+     * @example
+     * ```typescript
+     * const backend = new TesseractWasmBackend();
+     * backend.setProgressCallback((progress) => {
+     *   console.log(`OCR Progress: ${progress}%`);
+     *   document.getElementById('progress-bar').style.width = `${progress}%`;
+     * });
+     * ```
+     */
+    setProgressCallback(callback: (progress: number) => void): void;
+    /**
+     * Load language model from CDN
+     *
+     * Fetches the training data for a specific language from jsDelivr CDN.
+     * This is an MVP approach - models are cached by the browser.
+     *
+     * @param language - ISO 639-2/3 language code
+     * @throws {Error} If model download fails or language is not available
+     *
+     * @internal
+     */
+    private loadLanguageModel;
+    /**
+     * Convert image bytes or Base64 string to ImageBitmap
+     *
+     * Handles both Uint8Array and Base64-encoded image data, converting to
+     * ImageBitmap format required by Tesseract WASM.
+     *
+     * @param imageBytes - Image data as Uint8Array or Base64 string
+     * @returns Promise resolving to ImageBitmap
+     * @throws {Error} If conversion fails (browser API not available or invalid image data)
+     *
+     * @internal
+     */
+    private convertToImageBitmap;
+    /**
+     * Get confidence score from OCR result
+     *
+     * Attempts to retrieve confidence score from Tesseract.
+     * Returns a safe default if unavailable.
+     *
+     * @returns Confidence score between 0 and 1
+     *
+     * @internal
+     */
+    private getConfidenceScore;
+    /**
+     * Get page metadata from OCR result
+     *
+     * Retrieves additional metadata like image dimensions and processing info.
+     *
+     * @returns Metadata object (may be empty if unavailable)
+     *
+     * @internal
+     */
+    private getPageMetadata;
+    /**
+     * Dynamically load tesseract-wasm module
+     *
+     * Uses dynamic import to load tesseract-wasm only when needed,
+     * avoiding hard dependency in browser environments where it may not be bundled.
+     *
+     * @returns tesseract-wasm module object
+     * @throws {Error} If module cannot be imported
+     *
+     * @internal
+     */
+    private loadTesseractWasm;
+    /**
+     * Report progress to progress callback
+     *
+     * Internal helper for notifying progress updates during OCR processing.
+     *
+     * @param progress - Progress percentage (0-100)
+     *
+     * @internal
+     */
+    private reportProgress;
+}
+
+export { TesseractWasmBackend };