5397 lines
199 KiB
PHP
5397 lines
199 KiB
PHP
<?php
|
||
|
||
// This file is auto-generated by alef — DO NOT EDIT.
|
||
// alef:hash:4e15143f4af1ae8bafbdb1506ef057da924484c66a19483966333558ad437e75
|
||
// To regenerate: alef generate
|
||
// To verify freshness: alef verify --exit-code
|
||
// Issues & docs: https://github.com/kreuzberg-dev/alef
|
||
// Type stubs for the native PHP extension — declares classes
|
||
// provided at runtime by the compiled Rust extension (.so/.dll).
|
||
// Include this in phpstan.neon scanFiles for static analysis.
|
||
|
||
declare(strict_types=1);
|
||
|
||
namespace Kreuzberg {
|
||
class KreuzbergException extends \RuntimeException
|
||
{
|
||
public function getErrorCode(): int { throw new \RuntimeException('Not implemented.'); }
|
||
}
|
||
|
||
final class CacheStats
|
||
{
|
||
public function __construct(
|
||
/** @var int */
|
||
public readonly int $totalFiles,
|
||
/** @var float */
|
||
public readonly float $totalSizeMb,
|
||
/** @var float */
|
||
public readonly float $availableSpaceMb,
|
||
/** @var float */
|
||
public readonly float $oldestFileAgeDays,
|
||
/** @var float */
|
||
public readonly float $newestFileAgeDays
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Hardware acceleration configuration for ONNX Runtime models.
|
||
*
|
||
* Controls which execution provider (CPU, CoreML, CUDA, TensorRT) is used
|
||
* for inference in layout detection and embedding generation.
|
||
*
|
||
* # Example
|
||
*/
|
||
final class AccelerationConfig
|
||
{
|
||
public function __construct(
|
||
/** @var ExecutionProviderType Execution provider to use for ONNX inference. */
|
||
public readonly ExecutionProviderType $provider,
|
||
/** @var int GPU device ID (for CUDA/TensorRT). Ignored for CPU/CoreML/Auto. */
|
||
public readonly int $deviceId
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Cross-extractor content filtering configuration.
|
||
*
|
||
* Controls whether "furniture" content (headers, footers, page numbers,
|
||
* watermarks, repeating text) is included in or stripped from extraction
|
||
* results. Applies across all extractors (PDF, DOCX, RTF, ODT, HTML, etc.)
|
||
* with format-specific implementation.
|
||
*
|
||
* When `None` on `ExtractionConfig`, each extractor uses its current
|
||
* default behavior unchanged.
|
||
*/
|
||
final class ContentFilterConfig
|
||
{
|
||
public function __construct(
|
||
/**
|
||
* Include running headers in extraction output.
|
||
*
|
||
* - PDF: Disables top-margin furniture stripping and prevents the layout
|
||
* model from treating `PageHeader`-classified regions as furniture.
|
||
* - DOCX: Includes document headers in text output.
|
||
* - RTF/ODT: Headers already included; this is a no-op when true.
|
||
* - HTML/EPUB: Keeps `<header>` element content.
|
||
*
|
||
* Default: `false` (headers are stripped or excluded).
|
||
*
|
||
* @var bool
|
||
*/
|
||
public readonly bool $includeHeaders,
|
||
/**
|
||
* Include running footers in extraction output.
|
||
*
|
||
* - PDF: Disables bottom-margin furniture stripping and prevents the layout
|
||
* model from treating `PageFooter`-classified regions as furniture.
|
||
* - DOCX: Includes document footers in text output.
|
||
* - RTF/ODT: Footers already included; this is a no-op when true.
|
||
* - HTML/EPUB: Keeps `<footer>` element content.
|
||
*
|
||
* Default: `false` (footers are stripped or excluded).
|
||
*
|
||
* @var bool
|
||
*/
|
||
public readonly bool $includeFooters,
|
||
/**
|
||
* Enable the heuristic cross-page repeating text detector.
|
||
*
|
||
* When `true` (default), text that repeats verbatim across a supermajority
|
||
* of pages is classified as furniture and stripped. Disable this if brand
|
||
* names or repeated headings are being incorrectly removed by the heuristic.
|
||
*
|
||
* Note: when a layout-detection model is active, the model may independently
|
||
* classify page-header / page-footer regions as furniture on a per-page basis.
|
||
* To preserve those regions, set `include_headers = true`, `include_footers = true`,
|
||
* or both, in addition to disabling this flag.
|
||
*
|
||
* Primarily affects PDF extraction.
|
||
*
|
||
* Default: `true`.
|
||
*
|
||
* @var bool
|
||
*/
|
||
public readonly bool $stripRepeatingText,
|
||
/**
|
||
* Include watermark text in extraction output.
|
||
*
|
||
* - PDF: Keeps watermark artifacts and arXiv identifiers.
|
||
* - Other formats: No effect currently.
|
||
*
|
||
* Default: `false` (watermarks are stripped).
|
||
*
|
||
* @var bool
|
||
*/
|
||
public readonly bool $includeWatermarks
|
||
) { }
|
||
public static function default(): ContentFilterConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
}
|
||
|
||
/**
|
||
* Configuration for email extraction.
|
||
*/
|
||
final class EmailConfig
|
||
{
|
||
public function __construct(
|
||
/**
|
||
* Windows codepage number to use when an MSG file contains no codepage property.
|
||
* Defaults to `None`, which falls back to windows-1252.
|
||
*
|
||
* If an unrecognized or invalid codepage number is supplied (including 0),
|
||
* the behavior silently falls back to windows-1252 — the same as when the
|
||
* MSG file itself contains an unrecognized codepage. No error or warning is
|
||
* emitted. Users should verify output when supplying unusual values.
|
||
*
|
||
* Common values:
|
||
* - 1250: Central European (Polish, Czech, Hungarian, etc.)
|
||
* - 1251: Cyrillic (Russian, Ukrainian, Bulgarian, etc.)
|
||
* - 1252: Western European (default)
|
||
* - 1253: Greek
|
||
* - 1254: Turkish
|
||
* - 1255: Hebrew
|
||
* - 1256: Arabic
|
||
* - 932: Japanese (Shift-JIS)
|
||
* - 936: Simplified Chinese (GBK)
|
||
*
|
||
* @var ?int
|
||
*/
|
||
public readonly ?int $msgFallbackCodepage = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Main extraction configuration.
|
||
*
|
||
* This struct contains all configuration options for the extraction process.
|
||
* It can be loaded from TOML, YAML, or JSON files, or created programmatically.
|
||
*
|
||
* # Example
|
||
*/
|
||
final class ExtractionConfig
|
||
{
|
||
public function __construct(
|
||
/** @var bool Enable caching of extraction results */
|
||
public readonly bool $useCache,
|
||
/** @var bool Enable quality post-processing */
|
||
public readonly bool $enableQualityProcessing,
|
||
/** @var bool Force OCR even for searchable PDFs */
|
||
public readonly bool $forceOcr,
|
||
/**
|
||
* Disable OCR entirely, even for images.
|
||
*
|
||
* When `true`, OCR is skipped for all document types. Images return metadata
|
||
* only (dimensions, format, EXIF) without text extraction. PDFs use only
|
||
* native text extraction without OCR fallback.
|
||
*
|
||
* Cannot be `true` simultaneously with `force_ocr`.
|
||
*
|
||
* *Added in v4.7.0.*
|
||
*
|
||
* @var bool
|
||
*/
|
||
public readonly bool $disableOcr,
|
||
/**
|
||
* Result structure format
|
||
*
|
||
* Controls whether results are returned in unified format (default) with all
|
||
* content in the `content` field, or element-based format with semantic
|
||
* elements (for Unstructured-compatible output).
|
||
*
|
||
* @var ResultFormat
|
||
*/
|
||
public readonly ResultFormat $resultFormat,
|
||
/**
|
||
* Content text format (default: Plain).
|
||
*
|
||
* Controls the format of the extracted content:
|
||
* - `Plain`: Raw extracted text (default)
|
||
* - `Markdown`: Markdown formatted output
|
||
* - `Djot`: Djot markup format (requires djot feature)
|
||
* - `Html`: HTML formatted output
|
||
*
|
||
* When set to a structured format, extraction results will include
|
||
* formatted output. The `formatted_content` field may be populated
|
||
* when format conversion is applied.
|
||
*
|
||
* @var OutputFormat
|
||
*/
|
||
public readonly OutputFormat $outputFormat,
|
||
/**
|
||
* Run layout detection on the non-OCR PDF markdown path.
|
||
*
|
||
* When `true` and `layout` is `Some(_)`, layout regions inform heading,
|
||
* table, list, and figure detection in the structure pipeline that would
|
||
* otherwise rely on font-clustering heuristics alone. Significantly
|
||
* improves SF1 (structural F1) at the cost of inference latency
|
||
* (~150-300ms/page CPU, ~20-50ms/page GPU). Default: `false`.
|
||
* Requires the `layout-detection` feature.
|
||
*
|
||
* @var bool
|
||
*/
|
||
public readonly bool $useLayoutForMarkdown,
|
||
/**
|
||
* Enable structured document tree output.
|
||
*
|
||
* When true, populates the `document` field on `ExtractionResult` with a
|
||
* hierarchical `DocumentStructure` containing heading-driven section nesting,
|
||
* table grids, content layer classification, and inline annotations.
|
||
*
|
||
* Independent of `result_format` — can be combined with Unified or ElementBased.
|
||
*
|
||
* @var bool
|
||
*/
|
||
public readonly bool $includeDocumentStructure,
|
||
/**
|
||
* Maximum recursion depth for archive extraction (default: 3).
|
||
* Set to 0 to disable recursive extraction (legacy behavior).
|
||
*
|
||
* @var int
|
||
*/
|
||
public readonly int $maxArchiveDepth,
|
||
/** @var ?OcrConfig OCR configuration (None = OCR disabled) */
|
||
public readonly ?OcrConfig $ocr = null,
|
||
/**
|
||
* Force OCR on specific pages only (1-indexed page numbers, must be >= 1).
|
||
*
|
||
* When set, only the listed pages are OCR'd regardless of text layer quality.
|
||
* Unlisted pages use native text extraction. Ignored when `force_ocr` is `true`.
|
||
* Only applies to PDF documents. Duplicates are automatically deduplicated.
|
||
* An `ocr` config is recommended for backend/language selection; defaults are used if absent.
|
||
*
|
||
* @var ?array<int>
|
||
*/
|
||
public readonly ?array $forceOcrPages = null,
|
||
/** @var ?ChunkingConfig Text chunking configuration (None = chunking disabled) */
|
||
public readonly ?ChunkingConfig $chunking = null,
|
||
/**
|
||
* Content filtering configuration (None = use extractor defaults).
|
||
*
|
||
* Controls whether document "furniture" (headers, footers, watermarks,
|
||
* repeating text) is included in or stripped from extraction results.
|
||
* See [`ContentFilterConfig`] for per-field documentation.
|
||
*
|
||
* @var ?ContentFilterConfig
|
||
*/
|
||
public readonly ?ContentFilterConfig $contentFilter = null,
|
||
/** @var ?ImageExtractionConfig Image extraction configuration (None = no image extraction) */
|
||
public readonly ?ImageExtractionConfig $images = null,
|
||
/** @var ?PdfConfig PDF-specific options (None = use defaults) */
|
||
public readonly ?PdfConfig $pdfOptions = null,
|
||
/** @var ?TokenReductionOptions Token reduction configuration (None = no token reduction) */
|
||
public readonly ?TokenReductionOptions $tokenReduction = null,
|
||
/** @var ?LanguageDetectionConfig Language detection configuration (None = no language detection) */
|
||
public readonly ?LanguageDetectionConfig $languageDetection = null,
|
||
/** @var ?PageConfig Page extraction configuration (None = no page tracking) */
|
||
public readonly ?PageConfig $pages = null,
|
||
/** @var ?KeywordConfig Keyword extraction configuration (None = no keyword extraction) */
|
||
public readonly ?KeywordConfig $keywords = null,
|
||
/** @var ?PostProcessorConfig Post-processor configuration (None = use defaults) */
|
||
public readonly ?PostProcessorConfig $postprocessor = null,
|
||
/**
|
||
* HTML to Markdown conversion options (None = use defaults)
|
||
*
|
||
* Configure how HTML documents are converted to Markdown, including heading styles,
|
||
* list formatting, code block styles, and preprocessing options.
|
||
*
|
||
* @var ?string
|
||
*/
|
||
public readonly ?string $htmlOptions = null,
|
||
/**
|
||
* Styled HTML output configuration.
|
||
*
|
||
* When set alongside `output_format = OutputFormat::Html`, the extraction
|
||
* pipeline uses [`StyledHtmlRenderer`](crate::rendering::StyledHtmlRenderer)
|
||
* which emits stable `kb-*` CSS class hooks on every structural element
|
||
* and optionally embeds theme CSS or user-supplied CSS in a `<style>` block.
|
||
*
|
||
* When `None`, the existing plain comrak-based HTML renderer is used.
|
||
*
|
||
* @var ?HtmlOutputConfig
|
||
*/
|
||
public readonly ?HtmlOutputConfig $htmlOutput = null,
|
||
/**
|
||
* Default per-file timeout in seconds for batch extraction.
|
||
*
|
||
* When set, each file in a batch will be canceled after this duration
|
||
* unless overridden by [`FileExtractionConfig::timeout_secs`].
|
||
*
|
||
* Defaults to `Some(60)` to prevent pathological files (e.g. deeply
|
||
* nested archives, documents with millions of cells) from running
|
||
* indefinitely and exhausting caller resources. Set to `None` to
|
||
* disable the timeout for trusted input or long-running workloads.
|
||
*
|
||
* @var ?int
|
||
*/
|
||
public readonly ?int $extractionTimeoutSecs = null,
|
||
/**
|
||
* Maximum concurrent extractions in batch operations (None = (num_cpus × 1.5).ceil()).
|
||
*
|
||
* Limits parallelism to prevent resource exhaustion when processing
|
||
* large batches. Defaults to (num_cpus × 1.5).ceil() when not set.
|
||
*
|
||
* @var ?int
|
||
*/
|
||
public readonly ?int $maxConcurrentExtractions = null,
|
||
/**
|
||
* Security limits for archive extraction.
|
||
*
|
||
* Controls maximum archive size, compression ratio, file count, and other
|
||
* security thresholds to prevent decompression bomb attacks. Also caps
|
||
* nesting depth, iteration count, entity / token length, total
|
||
* content size, and table cell count for every extraction path that
|
||
* ingests user-controlled bytes.
|
||
* When `None`, default limits are used.
|
||
*
|
||
* @var ?SecurityLimits
|
||
*/
|
||
public readonly ?SecurityLimits $securityLimits = null,
|
||
/**
|
||
* Maximum uncompressed size in bytes for a single embedded file before
|
||
* recursive extraction is attempted (default: 50 MiB).
|
||
*
|
||
* Applies to embedded objects inside OOXML containers (DOCX, PPTX) and
|
||
* to email attachments processed via recursive extraction. Files that
|
||
* exceed this limit are skipped with a `ProcessingWarning` rather than
|
||
* passed to the extraction pipeline, preventing a single oversized
|
||
* embedded object from consuming unbounded memory or time.
|
||
*
|
||
* Set to `None` to disable the per-embedded-file cap (falls back to
|
||
* `security_limits.max_archive_size` as the only guard).
|
||
*
|
||
* @var ?int
|
||
*/
|
||
public readonly ?int $maxEmbeddedFileBytes = null,
|
||
/**
|
||
* Layout detection configuration (None = layout detection disabled).
|
||
*
|
||
* When set, PDF pages and images are analyzed for document structure
|
||
* (headings, code, formulas, tables, figures, etc.) using RT-DETR models
|
||
* via ONNX Runtime. For PDFs, layout hints override paragraph classification
|
||
* in the markdown pipeline. For images, per-region OCR is performed with
|
||
* markdown formatting based on detected layout classes.
|
||
* Requires the `layout-detection` feature to run inference; the field is
|
||
* present whenever the `layout-types` feature is active (which includes
|
||
* `layout-detection` as well as the no-ORT target groups).
|
||
*
|
||
* @var ?LayoutDetectionConfig
|
||
*/
|
||
public readonly ?LayoutDetectionConfig $layout = null,
|
||
/**
|
||
* Hardware acceleration configuration for ONNX Runtime models.
|
||
*
|
||
* Controls execution provider selection for layout detection and embedding
|
||
* models. When `None`, uses platform defaults (CoreML on macOS, CUDA on
|
||
* Linux, CPU on Windows).
|
||
*
|
||
* @var ?AccelerationConfig
|
||
*/
|
||
public readonly ?AccelerationConfig $acceleration = null,
|
||
/**
|
||
* Cache namespace for tenant isolation.
|
||
*
|
||
* When set, cache entries are stored under `{cache_dir}/{namespace}/`.
|
||
* Must be alphanumeric, hyphens, or underscores only (max 64 chars).
|
||
* Different namespaces have isolated cache spaces on the same filesystem.
|
||
*
|
||
* @var ?string
|
||
*/
|
||
public readonly ?string $cacheNamespace = null,
|
||
/**
|
||
* Per-request cache TTL in seconds.
|
||
*
|
||
* Overrides the global `max_age_days` for this specific extraction.
|
||
* When `0`, caching is completely skipped (no read or write).
|
||
* When `None`, the global TTL applies.
|
||
*
|
||
* @var ?int
|
||
*/
|
||
public readonly ?int $cacheTtlSecs = null,
|
||
/**
|
||
* Email extraction configuration (None = use defaults).
|
||
*
|
||
* Currently supports configuring the fallback codepage for MSG files
|
||
* that do not specify one. See `EmailConfig` for details.
|
||
*
|
||
* @var ?EmailConfig
|
||
*/
|
||
public readonly ?EmailConfig $email = null,
|
||
/**
|
||
* Concurrency limits for constrained environments (None = use defaults).
|
||
*
|
||
* Controls Rayon thread pool size, ONNX Runtime intra-op threads, and
|
||
* (when `max_concurrent_extractions` is unset) the batch concurrency
|
||
* semaphore. See `ConcurrencyConfig` for details.
|
||
*
|
||
* @var ?string
|
||
*/
|
||
public readonly ?string $concurrency = null,
|
||
/**
|
||
* Tree-sitter language pack configuration (None = tree-sitter disabled).
|
||
*
|
||
* When set, enables code file extraction using tree-sitter parsers.
|
||
* Controls grammar download behavior and code analysis options.
|
||
*
|
||
* @var ?TreeSitterConfig
|
||
*/
|
||
public readonly ?TreeSitterConfig $treeSitter = null,
|
||
/**
|
||
* Structured extraction via LLM (None = disabled).
|
||
*
|
||
* When set, the extracted document content is sent to an LLM with the
|
||
* provided JSON schema. The structured response is stored in
|
||
* `ExtractionResult::structured_output`.
|
||
*
|
||
* @var ?StructuredExtractionConfig
|
||
*/
|
||
public readonly ?StructuredExtractionConfig $structuredExtraction = null,
|
||
/**
|
||
* Cancellation token for this extraction (None = no external cancellation).
|
||
*
|
||
* Pass a [`CancellationToken`] clone here and call [`CancellationToken::cancel`]
|
||
* from another thread / task to abort the extraction in progress. The extractor
|
||
* checks the token at safe checkpoints (before lock acquisition, between pages,
|
||
* between batch items) and returns [`KreuzbergError::Cancelled`] when set.
|
||
*
|
||
* The field is excluded from serialization because `CancellationToken` is a
|
||
* runtime handle, not a configuration value.
|
||
*
|
||
* @var ?string
|
||
*/
|
||
public readonly ?string $cancelToken = null
|
||
) { }
|
||
public static function default(): ExtractionConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
public function needsImageProcessing(): bool
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
}
|
||
|
||
/**
|
||
* Per-file extraction configuration overrides for batch processing.
|
||
*
|
||
* All fields are `Option<T>` — `None` means "use the batch-level default."
|
||
* This type is used with `batch_extract_files` and
|
||
* `batch_extract_bytes` to allow heterogeneous
|
||
* extraction settings within a single batch.
|
||
*
|
||
* # Excluded Fields
|
||
*
|
||
* The following `ExtractionConfig` fields are batch-level only and
|
||
* cannot be overridden per file:
|
||
* - `max_concurrent_extractions` — controls batch parallelism
|
||
* - `use_cache` — global caching policy
|
||
* - `acceleration` — shared ONNX execution provider
|
||
* - `security_limits` — global archive security policy
|
||
*
|
||
* # Example
|
||
*/
|
||
final class FileExtractionConfig
|
||
{
|
||
public function __construct(
|
||
/** @var ?bool Override quality post-processing for this file. */
|
||
public readonly ?bool $enableQualityProcessing = null,
|
||
/** @var ?OcrConfig Override OCR configuration for this file (None in the Option = use batch default). */
|
||
public readonly ?OcrConfig $ocr = null,
|
||
/** @var ?bool Override force OCR for this file. */
|
||
public readonly ?bool $forceOcr = null,
|
||
/** @var ?array<int> Override force OCR pages for this file (1-indexed page numbers). */
|
||
public readonly ?array $forceOcrPages = null,
|
||
/** @var ?bool Override disable OCR for this file. */
|
||
public readonly ?bool $disableOcr = null,
|
||
/** @var ?ChunkingConfig Override chunking configuration for this file. */
|
||
public readonly ?ChunkingConfig $chunking = null,
|
||
/** @var ?ContentFilterConfig Override content filtering configuration for this file. */
|
||
public readonly ?ContentFilterConfig $contentFilter = null,
|
||
/** @var ?ImageExtractionConfig Override image extraction configuration for this file. */
|
||
public readonly ?ImageExtractionConfig $images = null,
|
||
/** @var ?PdfConfig Override PDF options for this file. */
|
||
public readonly ?PdfConfig $pdfOptions = null,
|
||
/** @var ?TokenReductionOptions Override token reduction for this file. */
|
||
public readonly ?TokenReductionOptions $tokenReduction = null,
|
||
/** @var ?LanguageDetectionConfig Override language detection for this file. */
|
||
public readonly ?LanguageDetectionConfig $languageDetection = null,
|
||
/** @var ?PageConfig Override page extraction for this file. */
|
||
public readonly ?PageConfig $pages = null,
|
||
/** @var ?KeywordConfig Override keyword extraction for this file. */
|
||
public readonly ?KeywordConfig $keywords = null,
|
||
/** @var ?PostProcessorConfig Override post-processor for this file. */
|
||
public readonly ?PostProcessorConfig $postprocessor = null,
|
||
/** @var ?string Override HTML conversion options for this file. */
|
||
public readonly ?string $htmlOptions = null,
|
||
/** @var ?ResultFormat Override result format for this file. */
|
||
public readonly ?ResultFormat $resultFormat = null,
|
||
/** @var ?OutputFormat Override output content format for this file. */
|
||
public readonly ?OutputFormat $outputFormat = null,
|
||
/** @var ?bool Override document structure output for this file. */
|
||
public readonly ?bool $includeDocumentStructure = null,
|
||
/** @var ?LayoutDetectionConfig Override layout detection for this file. */
|
||
public readonly ?LayoutDetectionConfig $layout = null,
|
||
/**
|
||
* Override per-file extraction timeout in seconds.
|
||
*
|
||
* When set, the extraction for this file will be canceled after the
|
||
* specified duration. A timed-out file produces an error result without
|
||
* affecting other files in the batch.
|
||
*
|
||
* @var ?int
|
||
*/
|
||
public readonly ?int $timeoutSecs = null,
|
||
/** @var ?TreeSitterConfig Override tree-sitter configuration for this file. */
|
||
public readonly ?TreeSitterConfig $treeSitter = null,
|
||
/**
|
||
* Override structured extraction configuration for this file.
|
||
*
|
||
* When set, enables LLM-based structured extraction with a JSON schema
|
||
* for this specific file. The extracted content is sent to a VLM/LLM
|
||
* and the response is parsed according to the provided schema.
|
||
*
|
||
* @var ?StructuredExtractionConfig
|
||
*/
|
||
public readonly ?StructuredExtractionConfig $structuredExtraction = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Batch item for byte array extraction.
|
||
*
|
||
* Used with `batch_extract_bytes` and `batch_extract_bytes_sync`
|
||
* to represent a single item in a batch extraction job.
|
||
*/
|
||
final class BatchBytesItem
|
||
{
|
||
public function __construct(
|
||
/** @var string The content bytes to extract from */
|
||
public readonly string $content,
|
||
/** @var string MIME type of the content (e.g., "application/pdf", "text/html") */
|
||
public readonly string $mimeType,
|
||
/** @var ?FileExtractionConfig Per-item configuration overrides (None uses batch-level defaults) */
|
||
public readonly ?FileExtractionConfig $config = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Batch item for file extraction.
|
||
*
|
||
* Used with `batch_extract_files` and `batch_extract_files_sync`
|
||
* to represent a single file in a batch extraction job.
|
||
*/
|
||
final class BatchFileItem
|
||
{
|
||
public function __construct(
|
||
/** @var string Path to the file to extract from */
|
||
public readonly string $path,
|
||
/** @var ?FileExtractionConfig Per-file configuration overrides (None uses batch-level defaults) */
|
||
public readonly ?FileExtractionConfig $config = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Image extraction configuration.
|
||
*/
|
||
final class ImageExtractionConfig
|
||
{
|
||
public function __construct(
|
||
/** @var bool Extract images from documents */
|
||
public readonly bool $extractImages,
|
||
/** @var int Target DPI for image normalization */
|
||
public readonly int $targetDpi,
|
||
/** @var int Maximum dimension for images (width or height) */
|
||
public readonly int $maxImageDimension,
|
||
/**
|
||
* Whether to inject image reference placeholders into markdown output.
|
||
* When `true` (default), image references like ``
|
||
* are appended to the markdown. Set to `false` to extract images as data
|
||
* without polluting the markdown output.
|
||
*
|
||
* @var bool
|
||
*/
|
||
public readonly bool $injectPlaceholders,
|
||
/** @var bool Automatically adjust DPI based on image content */
|
||
public readonly bool $autoAdjustDpi,
|
||
/** @var int Minimum DPI threshold */
|
||
public readonly int $minDpi,
|
||
/** @var int Maximum DPI threshold */
|
||
public readonly int $maxDpi,
|
||
/**
|
||
* When `true` (default), extracted images are classified by kind and grouped
|
||
* into clusters where they appear to belong to one figure.
|
||
*
|
||
* @var bool
|
||
*/
|
||
public readonly bool $classify,
|
||
/**
|
||
* When `true`, full-page renders produced during OCR preprocessing are captured
|
||
* and returned as `ImageKind::PageRaster` entries in `ExtractionResult.images`.
|
||
*
|
||
* **PDF + OCR only.** No rasters are captured for non-PDF inputs or when the
|
||
* document-level OCR bypass is active (whole-document backend). When OCR is
|
||
* enabled and this flag is set but the active backend skips per-page rendering,
|
||
* a `ProcessingWarning` is emitted in `ExtractionResult.processing_warnings`.
|
||
*
|
||
* Defaults to `false`. Enable when downstream consumers need page thumbnails
|
||
* (e.g. citation previews, visual grounding).
|
||
*
|
||
* @var bool
|
||
*/
|
||
public readonly bool $includePageRasters,
|
||
/**
|
||
* Run OCR on extracted images and include the recognized text in the document content.
|
||
*
|
||
* When `true` (default) and `ExtractionConfig.ocr` is configured, extracted images
|
||
* are processed with the configured OCR backend. Set to `false` to extract images
|
||
* without OCR processing, even when OCR is enabled.
|
||
*
|
||
* @var bool
|
||
*/
|
||
public readonly bool $runOcrOnImages,
|
||
/**
|
||
* When `true`, image OCR results are rendered as plain text without the
|
||
* `` markdown placeholder. Only takes effect when `run_ocr_on_images`
|
||
* is also `true`.
|
||
*
|
||
* @var bool
|
||
*/
|
||
public readonly bool $ocrTextOnly,
|
||
/**
|
||
* When `true` and `ocr_text_only` is `false`, append the OCR text after
|
||
* the image placeholder in the rendered output.
|
||
*
|
||
* @var bool
|
||
*/
|
||
public readonly bool $appendOcrText,
|
||
/**
|
||
* Maximum number of image objects to extract per PDF page.
|
||
*
|
||
* Some PDFs (e.g. technical diagrams stored as thousands of raster fragments)
|
||
* can trigger extremely long or indefinite extraction times when every image
|
||
* object on a dense page is decoded individually via the PDF extractor. Setting this
|
||
* limit causes kreuzberg to stop collecting individual images once the count
|
||
* per page reaches the cap and emit a warning instead.
|
||
*
|
||
* `None` (default) means no limit — all images are extracted.
|
||
*
|
||
* @var ?int
|
||
*/
|
||
public readonly ?int $maxImagesPerPage = null
|
||
) { }
|
||
public static function default(): ImageExtractionConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
}
|
||
|
||
/**
|
||
* Token reduction configuration.
|
||
*/
|
||
final class TokenReductionOptions
|
||
{
|
||
public function __construct(
|
||
/** @var string Reduction mode: "off", "light", "moderate", "aggressive", "maximum" */
|
||
public readonly string $mode,
|
||
/** @var bool Preserve important words (capitalized, technical terms) */
|
||
public readonly bool $preserveImportantWords
|
||
) { }
|
||
public static function default(): TokenReductionOptions
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
}
|
||
|
||
/**
|
||
* Language detection configuration.
|
||
*/
|
||
final class LanguageDetectionConfig
|
||
{
|
||
public function __construct(
|
||
/** @var bool Enable language detection */
|
||
public readonly bool $enabled,
|
||
/** @var float Minimum confidence threshold (0.0-1.0) */
|
||
public readonly float $minConfidence,
|
||
/** @var bool Detect multiple languages in the document */
|
||
public readonly bool $detectMultiple
|
||
) { }
|
||
public static function default(): LanguageDetectionConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
}
|
||
|
||
/**
|
||
* Configuration for styled HTML output.
|
||
*
|
||
* When set on `ExtractionConfig.html_output` alongside
|
||
* `output_format = OutputFormat.Html`, the pipeline builds a
|
||
* `StyledHtmlRenderer`(crate.rendering.StyledHtmlRenderer) instead of
|
||
* the plain comrak-based renderer.
|
||
*
|
||
* # Example
|
||
*/
|
||
final class HtmlOutputConfig
|
||
{
|
||
public function __construct(
|
||
/** @var HtmlTheme Built-in colour/typography theme. Default: [`HtmlTheme::Unstyled`]. */
|
||
public readonly HtmlTheme $theme,
|
||
/**
|
||
* CSS class prefix applied to every emitted class name.
|
||
*
|
||
* Default: `"kb-"`. Change this if your host application already uses
|
||
* classes that start with `kb-`.
|
||
*
|
||
* @var string
|
||
*/
|
||
public readonly string $classPrefix,
|
||
/**
|
||
* When `true` (default), write the resolved CSS into a `<style>` block
|
||
* immediately after the opening `<div class="{prefix}doc">`.
|
||
*
|
||
* Set to `false` to emit only the structural markup and wire up your
|
||
* own stylesheet targeting the `kb-*` class names.
|
||
*
|
||
* @var bool
|
||
*/
|
||
public readonly bool $embedCss,
|
||
/**
|
||
* Inline CSS string injected into the output after the theme stylesheet.
|
||
* Concatenated after `css_file` content when both are set.
|
||
*
|
||
* @var ?string
|
||
*/
|
||
public readonly ?string $css = null,
|
||
/**
|
||
* Path to a CSS file loaded once at renderer construction time.
|
||
* Concatenated before `css` when both are set.
|
||
*
|
||
* @var ?string
|
||
*/
|
||
public readonly ?string $cssFile = null
|
||
) { }
|
||
public static function default(): HtmlOutputConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
}
|
||
|
||
/**
|
||
* Layout detection configuration.
|
||
*
|
||
* Controls layout detection behavior in the extraction pipeline.
|
||
* When set on `ExtractionConfig`(super.ExtractionConfig), layout detection
|
||
* is enabled for PDF extraction.
|
||
*/
|
||
final class LayoutDetectionConfig
|
||
{
|
||
public function __construct(
|
||
/** @var bool Whether to apply postprocessing heuristics (default: true). */
|
||
public readonly bool $applyHeuristics,
|
||
/**
|
||
* Table structure recognition model.
|
||
*
|
||
* Controls which model is used for table cell detection within layout-detected
|
||
* table regions. Defaults to [`TableModel::Tatr`].
|
||
*
|
||
* @var TableModel
|
||
*/
|
||
public readonly TableModel $tableModel,
|
||
/** @var ?float Confidence threshold override (None = use model default). */
|
||
public readonly ?float $confidenceThreshold = null,
|
||
/**
|
||
* Hardware acceleration for ONNX models (layout detection + table structure).
|
||
*
|
||
* When set, controls which execution provider (CPU, CUDA, CoreML, TensorRT)
|
||
* is used for inference. Defaults to `None` (auto-select per platform).
|
||
*
|
||
* @var ?AccelerationConfig
|
||
*/
|
||
public readonly ?AccelerationConfig $acceleration = null
|
||
) { }
|
||
public static function default(): LayoutDetectionConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
}
|
||
|
||
/**
|
||
* Configuration for an LLM provider/model via liter-llm.
|
||
*
|
||
* Each feature (VLM OCR, VLM embeddings, structured extraction) carries
|
||
* its own `LlmConfig`, allowing different providers per feature.
|
||
*
|
||
* # Example
|
||
*
|
||
* ```toml
|
||
* [structured_extraction.llm]
|
||
* model = "openai/gpt-4o"
|
||
* api_key = "sk-..." # or use KREUZBERG_LLM_API_KEY env var
|
||
* ```
|
||
*/
|
||
final class LlmConfig
|
||
{
|
||
public function __construct(
|
||
/**
|
||
* Provider/model string using liter-llm routing format.
|
||
*
|
||
* Examples: `"openai/gpt-4o"`, `"anthropic/claude-sonnet-4-20250514"`,
|
||
* `"groq/llama-3.1-70b-versatile"`.
|
||
*
|
||
* @var string
|
||
*/
|
||
public readonly string $model,
|
||
/**
|
||
* API key for the provider. When `None`, liter-llm falls back to
|
||
* the provider's standard environment variable (e.g., `OPENAI_API_KEY`).
|
||
*
|
||
* @var ?string
|
||
*/
|
||
public readonly ?string $apiKey = null,
|
||
/** @var ?string Custom base URL override for the provider endpoint. */
|
||
public readonly ?string $baseUrl = null,
|
||
/** @var ?int Request timeout in seconds (default: 60). */
|
||
public readonly ?int $timeoutSecs = null,
|
||
/** @var ?int Maximum retry attempts (default: 3). */
|
||
public readonly ?int $maxRetries = null,
|
||
/** @var ?float Sampling temperature for generation tasks. */
|
||
public readonly ?float $temperature = null,
|
||
/** @var ?int Maximum tokens to generate. */
|
||
public readonly ?int $maxTokens = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Configuration for LLM-based structured data extraction.
|
||
*
|
||
* Sends extracted document content to a VLM with a JSON schema,
|
||
* returning structured data that conforms to the schema.
|
||
*
|
||
* # Example
|
||
*
|
||
* ```toml
|
||
* [structured_extraction]
|
||
* schema_name = "invoice_data"
|
||
* strict = true
|
||
*
|
||
* [structured_extraction.schema]
|
||
* type = "object"
|
||
* properties.vendor = { type = "string" }
|
||
* properties.total = { type = "number" }
|
||
* required = ["vendor", "total"]
|
||
*
|
||
* [structured_extraction.llm]
|
||
* model = "openai/gpt-4o"
|
||
* ```
|
||
*/
|
||
final class StructuredExtractionConfig
|
||
{
|
||
public function __construct(
|
||
/** @var string JSON Schema defining the desired output structure. */
|
||
public readonly string $schema,
|
||
/** @var string Schema name passed to the LLM's structured output mode. */
|
||
public readonly string $schemaName,
|
||
/** @var bool Enable strict mode — output must exactly match the schema. */
|
||
public readonly bool $strict,
|
||
/** @var LlmConfig LLM configuration for the extraction. */
|
||
public readonly LlmConfig $llm,
|
||
/** @var ?string Optional schema description for the LLM. */
|
||
public readonly ?string $schemaDescription = null,
|
||
/**
|
||
* Custom Jinja2 extraction prompt template. When `None`, a default template is used.
|
||
*
|
||
* Available template variables:
|
||
* - `{{ content }}` — The extracted document text.
|
||
* - `{{ schema }}` — The JSON schema as a formatted string.
|
||
* - `{{ schema_name }}` — The schema name.
|
||
* - `{{ schema_description }}` — The schema description (may be empty).
|
||
*
|
||
* @var ?string
|
||
*/
|
||
public readonly ?string $prompt = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Quality thresholds for OCR fallback decisions and pipeline quality gating.
|
||
*
|
||
* All fields default to the values that match the previous hardcoded behavior,
|
||
* so `OcrQualityThresholds.default()` preserves existing semantics exactly.
|
||
*/
|
||
final class OcrQualityThresholds
|
||
{
|
||
public function __construct(
|
||
/** @var int Minimum total non-whitespace characters to consider text substantive. */
|
||
public readonly int $minTotalNonWhitespace,
|
||
/** @var float Minimum non-whitespace characters per page on average. */
|
||
public readonly float $minNonWhitespacePerPage,
|
||
/** @var int Minimum character count for a word to be "meaningful". */
|
||
public readonly int $minMeaningfulWordLen,
|
||
/** @var int Minimum count of meaningful words before text is accepted. */
|
||
public readonly int $minMeaningfulWords,
|
||
/** @var float Minimum alphanumeric ratio (non-whitespace chars that are alphanumeric). */
|
||
public readonly float $minAlnumRatio,
|
||
/** @var int Minimum Unicode replacement characters (U+FFFD) to trigger OCR fallback. */
|
||
public readonly int $minGarbageChars,
|
||
/** @var float Maximum fraction of short (1-2 char) words before text is considered fragmented. */
|
||
public readonly float $maxFragmentedWordRatio,
|
||
/**
|
||
* Critical fragmentation threshold — triggers OCR regardless of meaningful words.
|
||
* Normal English text has ~20-30% short words. 80%+ is definitive garbage.
|
||
*
|
||
* @var float
|
||
*/
|
||
public readonly float $criticalFragmentedWordRatio,
|
||
/** @var float Minimum average word length. Below this with enough words indicates garbled extraction. */
|
||
public readonly float $minAvgWordLength,
|
||
/** @var int Minimum word count before average word length check applies. */
|
||
public readonly int $minWordsForAvgLengthCheck,
|
||
/** @var float Minimum consecutive word repetition ratio to detect column scrambling. */
|
||
public readonly float $minConsecutiveRepeatRatio,
|
||
/** @var int Minimum word count before consecutive repetition check is applied. */
|
||
public readonly int $minWordsForRepeatCheck,
|
||
/** @var int Minimum character count for "substantive markdown" OCR skip gate. */
|
||
public readonly int $substantiveMinChars,
|
||
/** @var int Minimum character count for "non-text content" OCR skip gate. */
|
||
public readonly int $nonTextMinChars,
|
||
/** @var float Alphanumeric+whitespace ratio threshold for skip decisions. */
|
||
public readonly float $alnumWsRatioThreshold,
|
||
/**
|
||
* Minimum quality score (0.0-1.0) for a pipeline stage result to be accepted.
|
||
* If the result from a backend scores below this, try the next backend.
|
||
*
|
||
* @var float
|
||
*/
|
||
public readonly float $pipelineMinQuality
|
||
) { }
|
||
public static function default(): OcrQualityThresholds
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
}
|
||
|
||
/**
|
||
* A single backend stage in the OCR pipeline.
|
||
*/
|
||
final class OcrPipelineStage
|
||
{
|
||
public function __construct(
|
||
/** @var string Backend name: "tesseract", "paddleocr", "easyocr", or a custom registered name. */
|
||
public readonly string $backend,
|
||
/** @var int Priority weight (higher = tried first). Stages are sorted by priority descending. */
|
||
public readonly int $priority,
|
||
/** @var ?string Language override for this stage (None = use parent OcrConfig.language). */
|
||
public readonly ?string $language = null,
|
||
/** @var ?TesseractConfig Tesseract-specific config override for this stage. */
|
||
public readonly ?TesseractConfig $tesseractConfig = null,
|
||
/** @var ?string PaddleOCR-specific config for this stage. */
|
||
public readonly ?string $paddleOcrConfig = null,
|
||
/** @var ?LlmConfig VLM config override for this pipeline stage. */
|
||
public readonly ?LlmConfig $vlmConfig = null,
|
||
/**
|
||
* Arbitrary per-call options passed through to the backend unchanged.
|
||
*
|
||
* Backends that support runtime tuning (mode switching, preprocessing
|
||
* flags, inference parameters, etc.) read this value and deserialize
|
||
* the keys they care about. Keys unknown to the backend are silently
|
||
* ignored, so options from different backends can coexist in the same
|
||
* config without conflict.
|
||
*
|
||
* Example (custom backend):
|
||
* ```json
|
||
* { "mode": "fast", "enable_layout": true }
|
||
* ```
|
||
*
|
||
* @var ?string
|
||
*/
|
||
public readonly ?string $backendOptions = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Multi-backend OCR pipeline with quality-based fallback.
|
||
*
|
||
* Backends are tried in priority order (highest first). After each backend
|
||
* produces output, quality is evaluated. If it meets `quality_thresholds.pipeline_min_quality`,
|
||
* the result is accepted. Otherwise the next backend is tried.
|
||
*/
|
||
final class OcrPipelineConfig
|
||
{
|
||
public function __construct(
|
||
/** @var array<OcrPipelineStage> Ordered list of backends to try. Sorted by priority (descending) at runtime. */
|
||
public readonly array $stages,
|
||
/** @var OcrQualityThresholds Quality thresholds for deciding whether to accept a result or try the next backend. */
|
||
public readonly OcrQualityThresholds $qualityThresholds
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* OCR configuration.
|
||
*/
|
||
final class OcrConfig
|
||
{
|
||
public function __construct(
|
||
/**
|
||
* Whether OCR is enabled.
|
||
*
|
||
* Setting `enabled: false` is a shorthand for `disable_ocr: true` on the parent
|
||
* [`ExtractionConfig`](crate::core::config::ExtractionConfig). Images return
|
||
* metadata only; PDFs use native text extraction without OCR fallback.
|
||
*
|
||
* Defaults to `true`. When `false`, all other OCR settings are ignored.
|
||
*
|
||
* @var bool
|
||
*/
|
||
public readonly bool $enabled,
|
||
/** @var string OCR backend: tesseract, easyocr, paddleocr */
|
||
public readonly string $backend,
|
||
/** @var string Language code (e.g., "eng", "deu") */
|
||
public readonly string $language,
|
||
/**
|
||
* Enable automatic page rotation based on orientation detection.
|
||
*
|
||
* When enabled, uses Tesseract's `DetectOrientationScript()` to detect
|
||
* page orientation (0/90/180/270 degrees) before OCR. If the page is
|
||
* rotated with high confidence, the image is corrected before recognition.
|
||
* This is critical for handling rotated scanned documents.
|
||
*
|
||
* @var bool
|
||
*/
|
||
public readonly bool $autoRotate,
|
||
/** @var ?TesseractConfig Tesseract-specific configuration (optional) */
|
||
public readonly ?TesseractConfig $tesseractConfig = null,
|
||
/** @var ?OutputFormat Output format for OCR results (optional, for format conversion) */
|
||
public readonly ?OutputFormat $outputFormat = null,
|
||
/** @var ?string PaddleOCR-specific configuration (optional, JSON passthrough) */
|
||
public readonly ?string $paddleOcrConfig = null,
|
||
/**
|
||
* Arbitrary per-call options passed through to the backend unchanged.
|
||
*
|
||
* Custom OCR backends and built-in backends that support runtime tuning
|
||
* can read this value and deserialize the keys they care about. Keys
|
||
* unknown to the backend are silently ignored.
|
||
*
|
||
* This is the recommended extension point for per-call parameters that
|
||
* are not covered by the typed fields above (e.g. mode switching,
|
||
* preprocessing flags, inference batch size).
|
||
*
|
||
* **Scope:** when `pipeline` is `None`, this value is propagated to the
|
||
* primary stage of the auto-constructed pipeline. When `pipeline` is
|
||
* explicitly set, this field has **no effect** — the caller must set
|
||
* `OcrPipelineStage.backend_options` directly on the relevant stage(s)
|
||
* instead.
|
||
*
|
||
* Example:
|
||
* ```json
|
||
* { "mode": "fast", "enable_layout": true, "timeout_ms": 5000 }
|
||
* ```
|
||
*
|
||
* @var ?string
|
||
*/
|
||
public readonly ?string $backendOptions = null,
|
||
/** @var ?OcrElementConfig OCR element extraction configuration */
|
||
public readonly ?OcrElementConfig $elementConfig = null,
|
||
/**
|
||
* Quality thresholds for the native-text-to-OCR fallback decision.
|
||
* When None, uses compiled defaults (matching previous hardcoded behavior).
|
||
*
|
||
* @var ?OcrQualityThresholds
|
||
*/
|
||
public readonly ?OcrQualityThresholds $qualityThresholds = null,
|
||
/**
|
||
* Multi-backend OCR pipeline configuration. When set, enables weighted
|
||
* fallback across multiple OCR backends based on output quality.
|
||
* When None, uses the single `backend` field (same as today).
|
||
*
|
||
* @var ?OcrPipelineConfig
|
||
*/
|
||
public readonly ?OcrPipelineConfig $pipeline = null,
|
||
/**
|
||
* VLM (Vision Language Model) OCR configuration.
|
||
*
|
||
* Required when `backend` is `"vlm"`. Uses liter-llm to send page
|
||
* images to a vision model for text extraction.
|
||
*
|
||
* @var ?LlmConfig
|
||
*/
|
||
public readonly ?LlmConfig $vlmConfig = null,
|
||
/**
|
||
* Custom Jinja2 prompt template for VLM OCR.
|
||
*
|
||
* When `None`, uses the default template. Available variables:
|
||
* - `{{ language }}` — The document language code (e.g., "eng", "deu").
|
||
*
|
||
* @var ?string
|
||
*/
|
||
public readonly ?string $vlmPrompt = null,
|
||
/**
|
||
* Hardware acceleration for ONNX Runtime models (e.g. PaddleOCR, layout detection).
|
||
*
|
||
* Not user-configurable via config files — injected at runtime from
|
||
* `ExtractionConfig::acceleration` before each `process_image` call.
|
||
*
|
||
* @var ?AccelerationConfig
|
||
*/
|
||
public readonly ?AccelerationConfig $acceleration = null,
|
||
/**
|
||
* Caller-supplied Tesseract `traineddata` bytes per language code.
|
||
*
|
||
* Primary use case is the WASM build, which has no filesystem and cannot
|
||
* download tessdata at runtime. Native builds typically rely on
|
||
* `TessdataManager` and ignore this field. When present, the WASM
|
||
* Tesseract backend prefers these bytes over its compile-time-bundled
|
||
* English data.
|
||
*
|
||
* Skipped by serde to keep config files small — supply via the typed API
|
||
* at runtime.
|
||
*
|
||
* @var ?array<string, string>
|
||
*/
|
||
public readonly ?array $tessdataBytes = null
|
||
) { }
|
||
public static function default(): OcrConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
}
|
||
|
||
/**
|
||
* Page extraction and tracking configuration.
|
||
*
|
||
* Controls how pages are extracted, tracked, and represented in the extraction results.
|
||
* When `None`, page tracking is disabled.
|
||
*
|
||
* Page range tracking in chunk metadata (first_page/last_page) is automatically enabled
|
||
* when page boundaries are available and chunking is configured.
|
||
*/
|
||
final class PageConfig
|
||
{
|
||
public function __construct(
|
||
/** @var bool Extract pages as separate array (ExtractionResult.pages) */
|
||
public readonly bool $extractPages,
|
||
/** @var bool Insert page markers in main content string */
|
||
public readonly bool $insertPageMarkers,
|
||
/**
|
||
* Page marker format (use {page_num} placeholder)
|
||
* Default: "\n\n<!-- PAGE {page_num} -->\n\n"
|
||
*
|
||
* @var string
|
||
*/
|
||
public readonly string $markerFormat
|
||
) { }
|
||
public static function default(): PageConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
}
|
||
|
||
/**
|
||
* PDF-specific configuration.
|
||
*/
|
||
final class PdfConfig
|
||
{
|
||
public function __construct(
|
||
/** @var bool Extract images from PDF */
|
||
public readonly bool $extractImages,
|
||
/**
|
||
* Extract tables from PDF.
|
||
*
|
||
* When `true` (default), runs pdf_oxide's native grid detector and, if it
|
||
* finds nothing, falls back to the heuristic text-layer reconstruction in
|
||
* `pdf::oxide::table::extract_tables_heuristic`. Set to `false` to skip
|
||
* both passes — `tables` will then be empty in the result.
|
||
*
|
||
* @var bool
|
||
*/
|
||
public readonly bool $extractTables,
|
||
/** @var bool Extract PDF metadata */
|
||
public readonly bool $extractMetadata,
|
||
/**
|
||
* Extract PDF annotations (text notes, highlights, links, stamps).
|
||
* Default: false
|
||
*
|
||
* @var bool
|
||
*/
|
||
public readonly bool $extractAnnotations,
|
||
/**
|
||
* Allow single-column pseudo tables in extraction results.
|
||
*
|
||
* By default, tables with fewer than 2 columns (layout-guided) or 3 columns
|
||
* (heuristic) are rejected. When `true`, the minimum column count is relaxed
|
||
* to 1, allowing single-column structured data (glossaries, itemized lists)
|
||
* to be emitted as tables. Other quality filters (density, sparsity, prose
|
||
* detection) still apply.
|
||
*
|
||
* @var bool
|
||
*/
|
||
public readonly bool $allowSingleColumnTables,
|
||
/**
|
||
* Perform OCR on inline images extracted from PDF pages and attach the
|
||
* recognized text to each `ExtractedImage.ocr_result`. Requires Tesseract
|
||
* to be available; if `ExtractionConfig.ocr` is `None` the extractor
|
||
* falls back to `TesseractConfig::default()`. Per-image failures degrade
|
||
* gracefully (the image is returned without OCR text rather than failing
|
||
* the whole extraction). Default: `false`.
|
||
*
|
||
* @var bool
|
||
*/
|
||
public readonly bool $ocrInlineImages,
|
||
/** @var ?array<string> List of passwords to try when opening encrypted PDFs */
|
||
public readonly ?array $passwords = null,
|
||
/** @var ?HierarchyConfig Hierarchy extraction configuration (None = hierarchy extraction disabled) */
|
||
public readonly ?HierarchyConfig $hierarchy = null,
|
||
/**
|
||
* Top margin fraction (0.0–1.0) of page height to exclude headers/running heads.
|
||
* Default: 0.06 (6%)
|
||
*
|
||
* @var ?float
|
||
*/
|
||
public readonly ?float $topMarginFraction = null,
|
||
/**
|
||
* Bottom margin fraction (0.0–1.0) of page height to exclude footers/page numbers.
|
||
* Default: 0.05 (5%)
|
||
*
|
||
* @var ?float
|
||
*/
|
||
public readonly ?float $bottomMarginFraction = null
|
||
) { }
|
||
public static function default(): PdfConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
}
|
||
|
||
/**
|
||
* Hierarchy extraction configuration for PDF text structure analysis.
|
||
*
|
||
* Enables extraction of document hierarchy levels (H1-H6) based on font size
|
||
* clustering and semantic analysis. When enabled, hierarchical blocks are
|
||
* included in page content.
|
||
*/
|
||
final class HierarchyConfig
|
||
{
|
||
public function __construct(
|
||
/** @var bool Enable hierarchy extraction */
|
||
public readonly bool $enabled,
|
||
/**
|
||
* Number of font size clusters to use for hierarchy levels (1-7)
|
||
*
|
||
* Default: 6, which provides H1-H6 heading levels with body text.
|
||
* Larger values create more fine-grained hierarchy levels.
|
||
*
|
||
* @var int
|
||
*/
|
||
public readonly int $kClusters,
|
||
/** @var bool Include bounding box information in hierarchy blocks */
|
||
public readonly bool $includeBbox,
|
||
/**
|
||
* OCR coverage threshold for smart OCR triggering (0.0-1.0)
|
||
*
|
||
* Determines when OCR should be triggered based on text block coverage.
|
||
* OCR is triggered when text blocks cover less than this fraction of the page.
|
||
* Default: 0.5 (trigger OCR if less than 50% of page has text)
|
||
*
|
||
* @var ?float
|
||
*/
|
||
public readonly ?float $ocrCoverageThreshold = null
|
||
) { }
|
||
public static function default(): HierarchyConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
}
|
||
|
||
/**
|
||
* Post-processor configuration.
|
||
*/
|
||
final class PostProcessorConfig
|
||
{
|
||
public function __construct(
|
||
/** @var bool Enable post-processors */
|
||
public readonly bool $enabled,
|
||
/** @var ?array<string> Whitelist of processor names to run (None = all enabled) */
|
||
public readonly ?array $enabledProcessors = null,
|
||
/** @var ?array<string> Blacklist of processor names to skip (None = none disabled) */
|
||
public readonly ?array $disabledProcessors = null,
|
||
/** @var ?array<string> Pre-computed AHashSet for O(1) enabled processor lookup */
|
||
public readonly ?array $enabledSet = null,
|
||
/** @var ?array<string> Pre-computed AHashSet for O(1) disabled processor lookup */
|
||
public readonly ?array $disabledSet = null
|
||
) { }
|
||
public static function default(): PostProcessorConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
}
|
||
|
||
/**
|
||
* Chunking configuration.
|
||
*
|
||
* Configures text chunking for document content, including chunk size,
|
||
* overlap, trimming behavior, and optional embeddings.
|
||
*
|
||
* Use `..Default.default()` when constructing to allow for future field additions:
|
||
*/
|
||
final class ChunkingConfig
|
||
{
|
||
public function __construct(
|
||
/**
|
||
* Maximum size per chunk (in units determined by `sizing`).
|
||
*
|
||
* When `sizing` is `Characters` (default), this is the max character count.
|
||
* When using token-based sizing, this is the max token count.
|
||
*
|
||
* Default: 1000
|
||
*
|
||
* @var int
|
||
*/
|
||
public readonly int $maxCharacters,
|
||
/**
|
||
* Overlap between chunks (in units determined by `sizing`).
|
||
*
|
||
* Default: 200
|
||
*
|
||
* @var int
|
||
*/
|
||
public readonly int $overlap,
|
||
/**
|
||
* Whether to trim whitespace from chunk boundaries.
|
||
*
|
||
* Default: true
|
||
*
|
||
* @var bool
|
||
*/
|
||
public readonly bool $trim,
|
||
/**
|
||
* Type of chunker to use (Text or Markdown).
|
||
*
|
||
* Default: Text
|
||
*
|
||
* @var ChunkerType
|
||
*/
|
||
public readonly ChunkerType $chunkerType,
|
||
/**
|
||
* How to measure chunk size.
|
||
*
|
||
* Default: `Characters` (Unicode character count).
|
||
* Enable `chunking-tiktoken` or `chunking-tokenizers` features for token-based sizing.
|
||
*
|
||
* @var ChunkSizing
|
||
*/
|
||
public readonly ChunkSizing $sizing,
|
||
/**
|
||
* When `true` and `chunker_type` is `Markdown`, prepend the heading hierarchy
|
||
* path (e.g. `"# Title > ## Section\n\n"`) to each chunk's content string.
|
||
*
|
||
* This is useful for RAG pipelines where each chunk needs self-contained
|
||
* context about its position in the document structure.
|
||
*
|
||
* Default: `false`
|
||
*
|
||
* @var bool
|
||
*/
|
||
public readonly bool $prependHeadingContext,
|
||
/** @var ?EmbeddingConfig Optional embedding configuration for chunk embeddings. */
|
||
public readonly ?EmbeddingConfig $embedding = null,
|
||
/** @var ?string Use a preset configuration (overrides individual settings if provided). */
|
||
public readonly ?string $preset = null,
|
||
/**
|
||
* Optional cosine similarity threshold for semantic topic boundary detection.
|
||
*
|
||
* Only used when `chunker_type` is `Semantic` and an `EmbeddingConfig` is
|
||
* provided. You almost never need to set this. When omitted, defaults to
|
||
* `0.75` which works well for most documents. Lower values detect more
|
||
* topic boundaries (more, smaller chunks); higher values detect fewer.
|
||
* Range: `0.0..=1.0`.
|
||
*
|
||
* @var ?float
|
||
*/
|
||
public readonly ?float $topicThreshold = null
|
||
) { }
|
||
public static function default(): ChunkingConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
}
|
||
|
||
/**
|
||
* Embedding configuration for text chunks.
|
||
*
|
||
* Configures embedding generation using ONNX models via the vendored embedding engine.
|
||
* Requires the `embeddings` feature to be enabled.
|
||
*/
|
||
final class EmbeddingConfig
|
||
{
|
||
public function __construct(
|
||
/** @var EmbeddingModelType The embedding model to use (defaults to "balanced" preset if not specified) */
|
||
public readonly EmbeddingModelType $model,
|
||
/** @var bool Whether to normalize embedding vectors (recommended for cosine similarity) */
|
||
public readonly bool $normalize,
|
||
/** @var int Batch size for embedding generation */
|
||
public readonly int $batchSize,
|
||
/** @var bool Show model download progress */
|
||
public readonly bool $showDownloadProgress,
|
||
/**
|
||
* Custom cache directory for model files
|
||
*
|
||
* Defaults to `~/.cache/kreuzberg/embeddings/` if not specified.
|
||
* Allows full customization of model download location.
|
||
*
|
||
* @var ?string
|
||
*/
|
||
public readonly ?string $cacheDir = null,
|
||
/**
|
||
* Hardware acceleration for the embedding ONNX model.
|
||
*
|
||
* When set, controls which execution provider (CPU, CUDA, CoreML, TensorRT)
|
||
* is used for inference. Defaults to `None` (auto-select per platform).
|
||
*
|
||
* @var ?AccelerationConfig
|
||
*/
|
||
public readonly ?AccelerationConfig $acceleration = null,
|
||
/**
|
||
* Maximum wall-clock duration (in seconds) for a single `embed()` call when
|
||
* using [`EmbeddingModelType::Plugin`].
|
||
*
|
||
* Applies only to the in-process plugin path — protects against hung
|
||
* host-language backends (e.g. a Python callback deadlocked on the GIL,
|
||
* a model stuck on CUDA OOM retries, etc.). On timeout, the dispatcher
|
||
* returns `Plugin` instead of blocking forever.
|
||
*
|
||
* `None` disables the timeout. The default (60 seconds) is conservative
|
||
* for common in-process inference; increase for large batches on slow
|
||
* hardware.
|
||
*
|
||
* @var ?int
|
||
*/
|
||
public readonly ?int $maxEmbedDurationSecs = null
|
||
) { }
|
||
public static function default(): EmbeddingConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
}
|
||
|
||
/**
|
||
* Configuration for tree-sitter language pack integration.
|
||
*
|
||
* Controls grammar download behavior and code analysis options.
|
||
*
|
||
* # Example (TOML)
|
||
*
|
||
* ```toml
|
||
* [tree_sitter]
|
||
* languages = ["python", "rust"]
|
||
* groups = ["web"]
|
||
*
|
||
* [tree_sitter.process]
|
||
* structure = true
|
||
* comments = true
|
||
* docstrings = true
|
||
* ```
|
||
*/
|
||
final class TreeSitterConfig
|
||
{
|
||
public function __construct(
|
||
/**
|
||
* Enable code intelligence processing (default: true).
|
||
*
|
||
* When `false`, tree-sitter analysis is completely skipped even if
|
||
* the config section is present.
|
||
*
|
||
* @var bool
|
||
*/
|
||
public readonly bool $enabled,
|
||
/** @var TreeSitterProcessConfig Processing options for code analysis. */
|
||
public readonly TreeSitterProcessConfig $process,
|
||
/**
|
||
* Custom cache directory for downloaded grammars.
|
||
*
|
||
* When `None`, uses the default: `~/.cache/tree-sitter-language-pack/v{version}/libs/`.
|
||
*
|
||
* @var ?string
|
||
*/
|
||
public readonly ?string $cacheDir = null,
|
||
/** @var ?array<string> Languages to pre-download on init (e.g., `["python", "rust"]`). */
|
||
public readonly ?array $languages = null,
|
||
/** @var ?array<string> Language groups to pre-download (e.g., `["web", "systems", "scripting"]`). */
|
||
public readonly ?array $groups = null
|
||
) { }
|
||
public static function default(): TreeSitterConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
}
|
||
|
||
/**
|
||
* Processing options for tree-sitter code analysis.
|
||
*
|
||
* Controls which analysis features are enabled when extracting code files.
|
||
*/
|
||
final class TreeSitterProcessConfig
|
||
{
|
||
public function __construct(
|
||
/** @var bool Extract structural items (functions, classes, structs, etc.). Default: true. */
|
||
public readonly bool $structure,
|
||
/** @var bool Extract import statements. Default: true. */
|
||
public readonly bool $imports,
|
||
/** @var bool Extract export statements. Default: true. */
|
||
public readonly bool $exports,
|
||
/** @var bool Extract comments. Default: false. */
|
||
public readonly bool $comments,
|
||
/** @var bool Extract docstrings. Default: false. */
|
||
public readonly bool $docstrings,
|
||
/** @var bool Extract symbol definitions. Default: false. */
|
||
public readonly bool $symbols,
|
||
/** @var bool Include parse diagnostics. Default: false. */
|
||
public readonly bool $diagnostics,
|
||
/** @var CodeContentMode Content rendering mode for code extraction. */
|
||
public readonly CodeContentMode $contentMode,
|
||
/** @var ?int Maximum chunk size in bytes. `None` disables chunking. */
|
||
public readonly ?int $chunkMaxSize = null
|
||
) { }
|
||
public static function default(): TreeSitterProcessConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
}
|
||
|
||
/**
|
||
* A supported document format entry.
|
||
*
|
||
* Represents a file extension and its corresponding MIME type that Kreuzberg can process.
|
||
*/
|
||
final class SupportedFormat
|
||
{
|
||
public function __construct(
|
||
/** @var string File extension (without leading dot), e.g., "pdf", "docx" */
|
||
public readonly string $extension,
|
||
/** @var string MIME type string, e.g., "application/pdf" */
|
||
public readonly string $mimeType
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* API server configuration.
|
||
*
|
||
* This struct holds all configuration options for the Kreuzberg API server,
|
||
* including host/port settings, CORS configuration, and upload limits.
|
||
*
|
||
* # Defaults
|
||
*
|
||
* - `host`: "127.0.0.1" (localhost only)
|
||
* - `port`: 8000
|
||
* - `cors_origins`: empty vector (allows all origins)
|
||
* - `max_request_body_bytes`: 104_857_600 (100 MB)
|
||
* - `max_multipart_field_bytes`: 104_857_600 (100 MB)
|
||
*/
|
||
final class ServerConfig
|
||
{
|
||
public function __construct(
|
||
/** @var string Server host address (e.g., "127.0.0.1", "0.0.0.0") */
|
||
public readonly string $host,
|
||
/** @var int Server port number */
|
||
public readonly int $port,
|
||
/**
|
||
* CORS allowed origins. Empty vector means allow all origins.
|
||
*
|
||
* If this is an empty vector, the server will accept requests from any origin.
|
||
* If populated with specific origins (e.g., `"https://example.com"`), only
|
||
* those origins will be allowed.
|
||
*
|
||
* @var array<string>
|
||
*/
|
||
public readonly array $corsOrigins,
|
||
/** @var int Maximum size of request body in bytes (default: 100 MB) */
|
||
public readonly int $maxRequestBodyBytes,
|
||
/** @var int Maximum size of multipart fields in bytes (default: 100 MB) */
|
||
public readonly int $maxMultipartFieldBytes
|
||
) { }
|
||
public static function default(): ServerConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
public function listenAddr(): string
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
public function corsAllowsAll(): bool
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
public function isOriginAllowed(string $origin): bool
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
public function maxRequestBodyMb(): int
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
public function maxMultipartFieldMb(): int
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
}
|
||
|
||
final class StructuredDataResult
|
||
{
|
||
public function __construct(
|
||
/** @var string */
|
||
public readonly string $content,
|
||
/** @var string */
|
||
public readonly string $format,
|
||
/** @var array<string, string> */
|
||
public readonly array $metadata,
|
||
/** @var array<string> */
|
||
public readonly array $textFields
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Application properties from docProps/app.xml for DOCX
|
||
*
|
||
* Contains Word-specific document statistics and metadata.
|
||
*/
|
||
final class DocxAppProperties
|
||
{
|
||
public function __construct(
|
||
/** @var ?string Application name (e.g., "Microsoft Office Word") */
|
||
public readonly ?string $application = null,
|
||
/** @var ?string Application version */
|
||
public readonly ?string $appVersion = null,
|
||
/** @var ?string Template filename */
|
||
public readonly ?string $template = null,
|
||
/** @var ?int Total editing time in minutes */
|
||
public readonly ?int $totalTime = null,
|
||
/** @var ?int Number of pages */
|
||
public readonly ?int $pages = null,
|
||
/** @var ?int Number of words */
|
||
public readonly ?int $words = null,
|
||
/** @var ?int Number of characters (excluding spaces) */
|
||
public readonly ?int $characters = null,
|
||
/** @var ?int Number of characters (including spaces) */
|
||
public readonly ?int $charactersWithSpaces = null,
|
||
/** @var ?int Number of lines */
|
||
public readonly ?int $lines = null,
|
||
/** @var ?int Number of paragraphs */
|
||
public readonly ?int $paragraphs = null,
|
||
/** @var ?string Company name */
|
||
public readonly ?string $company = null,
|
||
/** @var ?int Document security level */
|
||
public readonly ?int $docSecurity = null,
|
||
/** @var ?bool Scale crop flag */
|
||
public readonly ?bool $scaleCrop = null,
|
||
/** @var ?bool Links up to date flag */
|
||
public readonly ?bool $linksUpToDate = null,
|
||
/** @var ?bool Shared document flag */
|
||
public readonly ?bool $sharedDoc = null,
|
||
/** @var ?bool Hyperlinks changed flag */
|
||
public readonly ?bool $hyperlinksChanged = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Application properties from docProps/app.xml for XLSX
|
||
*
|
||
* Contains Excel-specific document metadata.
|
||
*/
|
||
final class XlsxAppProperties
|
||
{
|
||
public function __construct(
|
||
/** @var array<string> Worksheet names */
|
||
public readonly array $worksheetNames,
|
||
/** @var ?string Application name (e.g., "Microsoft Excel") */
|
||
public readonly ?string $application = null,
|
||
/** @var ?string Application version */
|
||
public readonly ?string $appVersion = null,
|
||
/** @var ?int Document security level */
|
||
public readonly ?int $docSecurity = null,
|
||
/** @var ?bool Scale crop flag */
|
||
public readonly ?bool $scaleCrop = null,
|
||
/** @var ?bool Links up to date flag */
|
||
public readonly ?bool $linksUpToDate = null,
|
||
/** @var ?bool Shared document flag */
|
||
public readonly ?bool $sharedDoc = null,
|
||
/** @var ?bool Hyperlinks changed flag */
|
||
public readonly ?bool $hyperlinksChanged = null,
|
||
/** @var ?string Company name */
|
||
public readonly ?string $company = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Application properties from docProps/app.xml for PPTX
|
||
*
|
||
* Contains PowerPoint-specific document metadata.
|
||
*/
|
||
final class PptxAppProperties
|
||
{
|
||
public function __construct(
|
||
/** @var array<string> Slide titles */
|
||
public readonly array $slideTitles,
|
||
/** @var ?string Application name (e.g., "Microsoft Office PowerPoint") */
|
||
public readonly ?string $application = null,
|
||
/** @var ?string Application version */
|
||
public readonly ?string $appVersion = null,
|
||
/** @var ?int Total editing time in minutes */
|
||
public readonly ?int $totalTime = null,
|
||
/** @var ?string Company name */
|
||
public readonly ?string $company = null,
|
||
/** @var ?int Document security level */
|
||
public readonly ?int $docSecurity = null,
|
||
/** @var ?bool Scale crop flag */
|
||
public readonly ?bool $scaleCrop = null,
|
||
/** @var ?bool Links up to date flag */
|
||
public readonly ?bool $linksUpToDate = null,
|
||
/** @var ?bool Shared document flag */
|
||
public readonly ?bool $sharedDoc = null,
|
||
/** @var ?bool Hyperlinks changed flag */
|
||
public readonly ?bool $hyperlinksChanged = null,
|
||
/** @var ?int Number of slides */
|
||
public readonly ?int $slides = null,
|
||
/** @var ?int Number of notes */
|
||
public readonly ?int $notes = null,
|
||
/** @var ?int Number of hidden slides */
|
||
public readonly ?int $hiddenSlides = null,
|
||
/** @var ?int Number of multimedia clips */
|
||
public readonly ?int $multimediaClips = null,
|
||
/** @var ?string Presentation format (e.g., "Widescreen", "Standard") */
|
||
public readonly ?string $presentationFormat = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Dublin Core metadata from docProps/core.xml
|
||
*
|
||
* Contains standard metadata fields defined by the Dublin Core standard
|
||
* and Office-specific extensions.
|
||
*/
|
||
final class CoreProperties
|
||
{
|
||
public function __construct(
|
||
/** @var ?string Document title */
|
||
public readonly ?string $title = null,
|
||
/** @var ?string Document subject/topic */
|
||
public readonly ?string $subject = null,
|
||
/** @var ?string Document creator/author */
|
||
public readonly ?string $creator = null,
|
||
/** @var ?string Keywords or tags */
|
||
public readonly ?string $keywords = null,
|
||
/** @var ?string Document description/abstract */
|
||
public readonly ?string $description = null,
|
||
/** @var ?string User who last modified the document */
|
||
public readonly ?string $lastModifiedBy = null,
|
||
/** @var ?string Revision number */
|
||
public readonly ?string $revision = null,
|
||
/** @var ?string Creation timestamp (ISO 8601) */
|
||
public readonly ?string $created = null,
|
||
/** @var ?string Last modification timestamp (ISO 8601) */
|
||
public readonly ?string $modified = null,
|
||
/** @var ?string Document category */
|
||
public readonly ?string $category = null,
|
||
/** @var ?string Content status (Draft, Final, etc.) */
|
||
public readonly ?string $contentStatus = null,
|
||
/** @var ?string Document language */
|
||
public readonly ?string $language = null,
|
||
/** @var ?string Unique identifier */
|
||
public readonly ?string $identifier = null,
|
||
/** @var ?string Document version */
|
||
public readonly ?string $version = null,
|
||
/** @var ?string Last print timestamp (ISO 8601) */
|
||
public readonly ?string $lastPrinted = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Configuration for security limits across extractors.
|
||
*
|
||
* All limits are intentionally conservative to prevent DoS attacks
|
||
* while still supporting legitimate documents.
|
||
*/
|
||
final class SecurityLimits
|
||
{
|
||
public function __construct(
|
||
/** @var int Maximum uncompressed size for archives (500 MB) */
|
||
public readonly int $maxArchiveSize,
|
||
/** @var int Maximum compression ratio before flagging as potential bomb (100:1) */
|
||
public readonly int $maxCompressionRatio,
|
||
/** @var int Maximum number of files in archive (10,000) */
|
||
public readonly int $maxFilesInArchive,
|
||
/** @var int Maximum nesting depth for structures (100) */
|
||
public readonly int $maxNestingDepth,
|
||
/**
|
||
* Maximum length of any single XML entity / attribute / token (1 MiB).
|
||
* This is a per-token cap, NOT a total cap — billion-laughs class
|
||
* attacks where a single entity expands to hundreds of MB are caught
|
||
* here, while normal long text content (a paragraph, a CDATA block) is
|
||
* caught by `max_content_size` instead.
|
||
*
|
||
* @var int
|
||
*/
|
||
public readonly int $maxEntityLength,
|
||
/** @var int Maximum string growth per document (100 MB) */
|
||
public readonly int $maxContentSize,
|
||
/** @var int Maximum iterations per operation */
|
||
public readonly int $maxIterations,
|
||
/** @var int Maximum XML depth (100 levels) */
|
||
public readonly int $maxXmlDepth,
|
||
/** @var int Maximum cells per table (100,000) */
|
||
public readonly int $maxTableCells
|
||
) { }
|
||
public static function default(): SecurityLimits
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
}
|
||
|
||
final class TokenReductionConfig
|
||
{
|
||
public function __construct(
|
||
/** @var ReductionLevel */
|
||
public readonly ReductionLevel $level,
|
||
/** @var bool */
|
||
public readonly bool $preserveMarkdown,
|
||
/** @var bool */
|
||
public readonly bool $preserveCode,
|
||
/** @var float */
|
||
public readonly float $semanticThreshold,
|
||
/** @var bool */
|
||
public readonly bool $enableParallel,
|
||
/** @var bool */
|
||
public readonly bool $useSimd,
|
||
/** @var array<string> */
|
||
public readonly array $preservePatterns,
|
||
/** @var bool */
|
||
public readonly bool $enableSemanticClustering,
|
||
/** @var ?string */
|
||
public readonly ?string $languageHint = null,
|
||
/** @var ?array<string, array<string>> */
|
||
public readonly ?array $customStopwords = null,
|
||
/** @var ?float */
|
||
public readonly ?float $targetReduction = null
|
||
) { }
|
||
public static function default(): TokenReductionConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
}
|
||
|
||
/**
|
||
* A PDF annotation extracted from a document page.
|
||
*/
|
||
final class PdfAnnotation
|
||
{
|
||
public function __construct(
|
||
/** @var PdfAnnotationType The type of annotation. */
|
||
public readonly PdfAnnotationType $annotationType,
|
||
/** @var int Page number where the annotation appears (1-indexed). */
|
||
public readonly int $pageNumber,
|
||
/** @var ?string Text content of the annotation (e.g., comment text, link URL). */
|
||
public readonly ?string $content = null,
|
||
/** @var ?BoundingBox Bounding box of the annotation on the page. */
|
||
public readonly ?BoundingBox $boundingBox = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Comprehensive Djot document structure with semantic preservation.
|
||
*
|
||
* This type captures the full richness of Djot markup, including:
|
||
* - Block-level structures (headings, lists, blockquotes, code blocks, etc.)
|
||
* - Inline formatting (emphasis, strong, highlight, subscript, superscript, etc.)
|
||
* - Attributes (classes, IDs, key-value pairs)
|
||
* - Links, images, footnotes
|
||
* - Math expressions (inline and display)
|
||
* - Tables with full structure
|
||
*
|
||
* Available when the `djot` feature is enabled.
|
||
*/
|
||
final class DjotContent
|
||
{
|
||
public function __construct(
|
||
/** @var string Plain text representation for backwards compatibility */
|
||
public readonly string $plainText,
|
||
/** @var array<FormattedBlock> Structured block-level content */
|
||
public readonly array $blocks,
|
||
/** @var Metadata Metadata from YAML frontmatter */
|
||
public readonly Metadata $metadata,
|
||
/** @var array<Table> Extracted tables as structured data */
|
||
public readonly array $tables,
|
||
/** @var array<DjotImage> Extracted images with metadata */
|
||
public readonly array $images,
|
||
/** @var array<DjotLink> Extracted links with URLs */
|
||
public readonly array $links,
|
||
/** @var array<Footnote> Footnote definitions */
|
||
public readonly array $footnotes,
|
||
/** @var array<string> Attributes mapped by element identifier (if present) */
|
||
public readonly array $attributes
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Block-level element in a Djot document.
|
||
*
|
||
* Represents structural elements like headings, paragraphs, lists, code blocks, etc.
|
||
*/
|
||
final class FormattedBlock
|
||
{
|
||
public function __construct(
|
||
/** @var BlockType Type of block element */
|
||
public readonly BlockType $blockType,
|
||
/** @var array<InlineElement> Inline content within the block */
|
||
public readonly array $inlineContent,
|
||
/** @var array<FormattedBlock> Nested blocks for containers (blockquotes, list items, divs) */
|
||
public readonly array $children,
|
||
/** @var ?int Heading level (1-6) for headings, or nesting level for lists */
|
||
public readonly ?int $level = null,
|
||
/** @var ?string Element attributes (classes, IDs, key-value pairs) */
|
||
public readonly ?string $attributes = null,
|
||
/** @var ?string Language identifier for code blocks */
|
||
public readonly ?string $language = null,
|
||
/** @var ?string Raw code content for code blocks */
|
||
public readonly ?string $code = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Inline element within a block.
|
||
*
|
||
* Represents text with formatting, links, images, etc.
|
||
*/
|
||
final class InlineElement
|
||
{
|
||
public function __construct(
|
||
/** @var InlineType Type of inline element */
|
||
public readonly InlineType $elementType,
|
||
/** @var string Text content */
|
||
public readonly string $content,
|
||
/** @var ?string Element attributes */
|
||
public readonly ?string $attributes = null,
|
||
/** @var ?array<string, string> Additional metadata (e.g., href for links, src/alt for images) */
|
||
public readonly ?array $metadata = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Image element in Djot.
|
||
*/
|
||
final class DjotImage
|
||
{
|
||
public function __construct(
|
||
/** @var string Image source URL or path */
|
||
public readonly string $src,
|
||
/** @var string Alternative text */
|
||
public readonly string $alt,
|
||
/** @var ?string Optional title */
|
||
public readonly ?string $title = null,
|
||
/** @var ?string Element attributes */
|
||
public readonly ?string $attributes = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Link element in Djot.
|
||
*/
|
||
final class DjotLink
|
||
{
|
||
public function __construct(
|
||
/** @var string Link URL */
|
||
public readonly string $url,
|
||
/** @var string Link text content */
|
||
public readonly string $text,
|
||
/** @var ?string Optional title */
|
||
public readonly ?string $title = null,
|
||
/** @var ?string Element attributes */
|
||
public readonly ?string $attributes = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Footnote in Djot.
|
||
*/
|
||
final class Footnote
|
||
{
|
||
public function __construct(
|
||
/** @var string Footnote label */
|
||
public readonly string $label,
|
||
/** @var array<FormattedBlock> Footnote content blocks */
|
||
public readonly array $content
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Top-level structured document representation.
|
||
*
|
||
* A flat array of nodes with index-based parent/child references forming a tree.
|
||
* Root-level nodes have `parent: None`. Use `body_roots()` and `furniture_roots()`
|
||
* to iterate over top-level content by layer.
|
||
*
|
||
* # Validation
|
||
*
|
||
* Call `validate()` after construction to verify all node indices are in bounds
|
||
* and parent-child relationships are bidirectionally consistent.
|
||
*/
|
||
final class DocumentStructure
|
||
{
|
||
public function __construct(
|
||
/** @var array<DocumentNode> All nodes in document/reading order. */
|
||
public readonly array $nodes,
|
||
/**
|
||
* Resolved relationships between nodes (footnote refs, citations, anchor links, etc.).
|
||
*
|
||
* Populated during derivation from the internal document representation.
|
||
* Empty when no relationships are detected.
|
||
*
|
||
* @var array<DocumentRelationship>
|
||
*/
|
||
public readonly array $relationships,
|
||
/**
|
||
* Sorted, deduplicated list of node type names present in this document.
|
||
*
|
||
* Each value is the snake_case `node_type` tag of the corresponding
|
||
* [`NodeContent`] variant (e.g. `"paragraph"`, `"heading"`, `"table"`, …).
|
||
*
|
||
* Computed from [`nodes`] via [`DocumentStructure::finalize_node_types`].
|
||
* Empty until that method is called (internal construction paths call it
|
||
* at the end of derivation).
|
||
*
|
||
* @var array<string>
|
||
*/
|
||
public readonly array $nodeTypes,
|
||
/**
|
||
* Origin format identifier (e.g. "docx", "pptx", "html", "pdf").
|
||
*
|
||
* Allows renderers to apply format-aware heuristics when converting
|
||
* the document tree to output formats.
|
||
*
|
||
* @var ?string
|
||
*/
|
||
public readonly ?string $sourceFormat = null
|
||
) { }
|
||
public function finalizeNodeTypes(): void
|
||
{ }
|
||
public function isEmpty(): bool
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
public static function default(): DocumentStructure
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
}
|
||
|
||
/**
|
||
* A resolved relationship between two nodes in the document tree.
|
||
*/
|
||
final class DocumentRelationship
|
||
{
|
||
public function __construct(
|
||
/** @var int Source node index (the referencing node). */
|
||
public readonly int $source,
|
||
/** @var int Target node index (the referenced node). */
|
||
public readonly int $target,
|
||
/** @var RelationshipKind Semantic kind of the relationship. */
|
||
public readonly RelationshipKind $kind
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* A single node in the document tree.
|
||
*
|
||
* Each node has deterministic `id`, typed `content`, optional `parent`/`children`
|
||
* for tree structure, and metadata like page number, bounding box, and content layer.
|
||
*/
|
||
final class DocumentNode
|
||
{
|
||
public function __construct(
|
||
/** @var string Deterministic identifier (hash of content + position). */
|
||
public readonly string $id,
|
||
/** @var NodeContent Node content — tagged enum, type-specific data only. */
|
||
public readonly NodeContent $content,
|
||
/** @var array<int> Child node indices in reading order. */
|
||
public readonly array $children,
|
||
/** @var ContentLayer Content layer classification. */
|
||
public readonly ContentLayer $contentLayer,
|
||
/**
|
||
* Inline annotations (formatting, links) on this node's text content.
|
||
*
|
||
* Only meaningful for text-carrying nodes; empty for containers.
|
||
*
|
||
* @var array<TextAnnotation>
|
||
*/
|
||
public readonly array $annotations,
|
||
/** @var ?int Parent node index (`None` = root-level node). */
|
||
public readonly ?int $parent = null,
|
||
/** @var ?int Page number where this node starts (1-indexed). */
|
||
public readonly ?int $page = null,
|
||
/** @var ?int Page number where this node ends (for multi-page tables/sections). */
|
||
public readonly ?int $pageEnd = null,
|
||
/** @var ?BoundingBox Bounding box in document coordinates. */
|
||
public readonly ?BoundingBox $bbox = null,
|
||
/**
|
||
* Format-specific key-value attributes.
|
||
*
|
||
* Extensible bag for miscellaneous data without a dedicated typed field: CSS classes,
|
||
* LaTeX environment names, Excel cell formulas, slide layout names, etc.
|
||
*
|
||
* @var ?array<string, string>
|
||
*/
|
||
public readonly ?array $attributes = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Structured table grid with cell-level metadata.
|
||
*
|
||
* Stores row/column dimensions and a flat list of cells with position info.
|
||
*/
|
||
final class TableGrid
|
||
{
|
||
public function __construct(
|
||
/** @var int Number of rows in the table. */
|
||
public readonly int $rows,
|
||
/** @var int Number of columns in the table. */
|
||
public readonly int $cols,
|
||
/** @var array<GridCell> All cells in row-major order. */
|
||
public readonly array $cells
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Individual grid cell with position and span metadata.
|
||
*/
|
||
final class GridCell
|
||
{
|
||
public function __construct(
|
||
/** @var string Cell text content. */
|
||
public readonly string $content,
|
||
/** @var int Zero-indexed row position. */
|
||
public readonly int $row,
|
||
/** @var int Zero-indexed column position. */
|
||
public readonly int $col,
|
||
/** @var int Number of rows this cell spans. */
|
||
public readonly int $rowSpan,
|
||
/** @var int Number of columns this cell spans. */
|
||
public readonly int $colSpan,
|
||
/** @var bool Whether this is a header cell. */
|
||
public readonly bool $isHeader,
|
||
/** @var ?BoundingBox Bounding box for this cell (if available). */
|
||
public readonly ?BoundingBox $bbox = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Inline text annotation — byte-range based formatting and links.
|
||
*
|
||
* Annotations reference byte offsets into the node's text content,
|
||
* enabling precise identification of formatted regions.
|
||
*/
|
||
final class TextAnnotation
|
||
{
|
||
public function __construct(
|
||
/** @var int Start byte offset in the node's text content (inclusive). */
|
||
public readonly int $start,
|
||
/** @var int End byte offset in the node's text content (exclusive). */
|
||
public readonly int $end,
|
||
/** @var AnnotationKind Annotation type. */
|
||
public readonly AnnotationKind $kind
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* General extraction result used by the core extraction API.
|
||
*
|
||
* This is the main result type returned by all extraction functions.
|
||
*/
|
||
final class ExtractionResult
|
||
{
|
||
public function __construct(
|
||
/** @var string */
|
||
public readonly string $content,
|
||
/** @var string */
|
||
public readonly string $mimeType,
|
||
/** @var Metadata */
|
||
public readonly Metadata $metadata,
|
||
/** @var array<Table> */
|
||
public readonly array $tables,
|
||
/**
|
||
* Non-fatal warnings collected during processing pipeline stages.
|
||
*
|
||
* Captures errors from optional pipeline features (embedding, chunking,
|
||
* language detection, output formatting) that don't prevent extraction
|
||
* but may indicate degraded results.
|
||
* Previously stored as individual keys in `metadata.additional`.
|
||
*
|
||
* @var array<ProcessingWarning>
|
||
*/
|
||
public readonly array $processingWarnings,
|
||
/**
|
||
* Extraction strategy used to produce the returned text.
|
||
*
|
||
* Populated when the extractor can reliably distinguish native text extraction,
|
||
* OCR-only extraction, or mixed native/OCR output.
|
||
*
|
||
* @var ?ExtractionMethod
|
||
*/
|
||
public readonly ?ExtractionMethod $extractionMethod = null,
|
||
/** @var ?array<string> */
|
||
public readonly ?array $detectedLanguages = null,
|
||
/**
|
||
* Text chunks when chunking is enabled.
|
||
*
|
||
* When chunking configuration is provided, the content is split into
|
||
* overlapping chunks for efficient processing. Each chunk contains the text,
|
||
* optional embeddings (if enabled), and metadata about its position.
|
||
*
|
||
* @var ?array<Chunk>
|
||
*/
|
||
public readonly ?array $chunks = null,
|
||
/**
|
||
* Extracted images from the document.
|
||
*
|
||
* When image extraction is enabled via `ImageExtractionConfig`, this field
|
||
* contains all images found in the document with their raw data and metadata.
|
||
* Each image may optionally contain a nested `ocr_result` if OCR was performed.
|
||
*
|
||
* @var ?array<ExtractedImage>
|
||
*/
|
||
public readonly ?array $images = null,
|
||
/**
|
||
* Per-page content when page extraction is enabled.
|
||
*
|
||
* When page extraction is configured, the document is split into per-page content
|
||
* with tables and images mapped to their respective pages.
|
||
*
|
||
* @var ?array<PageContent>
|
||
*/
|
||
public readonly ?array $pages = null,
|
||
/**
|
||
* Semantic elements when element-based result format is enabled.
|
||
*
|
||
* 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.
|
||
*
|
||
* @var ?array<Element>
|
||
*/
|
||
public readonly ?array $elements = null,
|
||
/**
|
||
* Rich Djot content structure (when extracting Djot documents).
|
||
*
|
||
* When extracting Djot documents with structured extraction enabled,
|
||
* this field contains the full semantic structure including:
|
||
* - Block-level elements with nesting
|
||
* - Inline formatting with attributes
|
||
* - Links, images, footnotes
|
||
* - Math expressions
|
||
* - Complete attribute information
|
||
*
|
||
* The `content` field still contains plain text for backward compatibility.
|
||
*
|
||
* Always `None` for non-Djot documents.
|
||
*
|
||
* @var ?DjotContent
|
||
*/
|
||
public readonly ?DjotContent $djotContent = null,
|
||
/**
|
||
* OCR elements with full spatial and confidence metadata.
|
||
*
|
||
* When OCR is performed with element extraction enabled, this field contains
|
||
* the structured representation of detected text including:
|
||
* - Bounding geometry (rectangles or quadrilaterals)
|
||
* - Confidence scores (detection and recognition)
|
||
* - Rotation information
|
||
* - Hierarchical relationships (Tesseract only)
|
||
*
|
||
* This field preserves all metadata that would otherwise be lost when
|
||
* converting to plain text or markdown output formats.
|
||
*
|
||
* Only populated when `OcrElementConfig.include_elements` is true.
|
||
*
|
||
* @var ?array<OcrElement>
|
||
*/
|
||
public readonly ?array $ocrElements = null,
|
||
/**
|
||
* Structured document tree (when document structure extraction is enabled).
|
||
*
|
||
* When `include_document_structure` is true in `ExtractionConfig`, this field
|
||
* contains the full hierarchical representation of the document including:
|
||
* - Heading-driven section nesting
|
||
* - Table grids with cell-level metadata
|
||
* - Content layer classification (body, header, footer, footnote)
|
||
* - Inline text annotations (formatting, links)
|
||
* - Bounding boxes and page numbers
|
||
*
|
||
* Independent of `result_format` — can be combined with Unified or ElementBased.
|
||
*
|
||
* @var ?DocumentStructure
|
||
*/
|
||
public readonly ?DocumentStructure $document = null,
|
||
/**
|
||
* Extracted keywords when keyword extraction is enabled.
|
||
*
|
||
* When keyword extraction (RAKE or YAKE) is configured, this field contains
|
||
* the extracted keywords with scores, algorithm info, and position data.
|
||
* Previously stored in `metadata.additional["keywords"]`.
|
||
*
|
||
* @var ?array<Keyword>
|
||
*/
|
||
public readonly ?array $extractedKeywords = null,
|
||
/**
|
||
* Document quality score from quality analysis.
|
||
*
|
||
* A value between 0.0 and 1.0 indicating the overall text quality.
|
||
* Previously stored in `metadata.additional["quality_score"]`.
|
||
*
|
||
* @var ?float
|
||
*/
|
||
public readonly ?float $qualityScore = null,
|
||
/**
|
||
* PDF annotations extracted from the document.
|
||
*
|
||
* When annotation extraction is enabled via `PdfConfig::extract_annotations`,
|
||
* this field contains text notes, highlights, links, stamps, and other
|
||
* annotations found in PDF documents.
|
||
*
|
||
* @var ?array<PdfAnnotation>
|
||
*/
|
||
public readonly ?array $annotations = null,
|
||
/**
|
||
* Nested extraction results from archive contents.
|
||
*
|
||
* When extracting archives, each processable file inside produces its own
|
||
* full extraction result. Set to `None` for non-archive formats.
|
||
* Use `max_archive_depth` in config to control recursion depth.
|
||
*
|
||
* @var ?array<ArchiveEntry>
|
||
*/
|
||
public readonly ?array $children = null,
|
||
/**
|
||
* URIs/links discovered during document extraction.
|
||
*
|
||
* Contains hyperlinks, image references, citations, email addresses, and
|
||
* other URI-like references found in the document. Always extracted when
|
||
* present in the source document.
|
||
*
|
||
* @var ?array<ExtractedUri>
|
||
*/
|
||
public readonly ?array $uris = null,
|
||
/**
|
||
* Tracked changes embedded in the source document.
|
||
*
|
||
* Populated by per-format extractors that understand change-tracking
|
||
* metadata (DOCX `w:ins`/`w:del`/`w:rPrChange`, ODT `text:change-*`,
|
||
* …). Every extractor defaults to `None` until its format-specific
|
||
* implementation is added. Extractors that do populate this field follow
|
||
* the "accepted-changes" convention: inserted text is present in
|
||
* `content`, deleted text is absent — the revision list is the separate
|
||
* audit trail.
|
||
*
|
||
* @var ?array<DocumentRevision>
|
||
*/
|
||
public readonly ?array $revisions = null,
|
||
/**
|
||
* Structured extraction output from LLM-based JSON schema extraction.
|
||
*
|
||
* When `structured_extraction` is configured in `ExtractionConfig`, the
|
||
* extracted document content is sent to a VLM with the provided JSON schema.
|
||
* The response is parsed and stored here as a JSON value matching the schema.
|
||
*
|
||
* @var ?string
|
||
*/
|
||
public readonly ?string $structuredOutput = null,
|
||
/**
|
||
* Code intelligence results from tree-sitter analysis.
|
||
*
|
||
* Populated when extracting source code files with the `tree-sitter` feature.
|
||
* Contains metrics, structural analysis, imports/exports, comments,
|
||
* docstrings, symbols, diagnostics, and optionally chunked code segments.
|
||
*
|
||
* Stored as an opaque JSON value so that all language bindings (Go, Java,
|
||
* C#, …) can deserialize it as a raw JSON object rather than a typed struct.
|
||
* The underlying type is `tree_sitter_language_pack::ProcessResult`.
|
||
*
|
||
* @var ?string
|
||
*/
|
||
public readonly ?string $codeIntelligence = null,
|
||
/**
|
||
* LLM token usage and cost data for all LLM calls made during this extraction.
|
||
*
|
||
* Contains one entry per LLM call. Multiple entries are produced when
|
||
* VLM OCR, structured extraction, or LLM embeddings run during
|
||
* the same extraction.
|
||
*
|
||
* `None` when no LLM was used.
|
||
*
|
||
* @var ?array<LlmUsage>
|
||
*/
|
||
public readonly ?array $llmUsage = null,
|
||
/**
|
||
* Pre-rendered content in the requested output format.
|
||
*
|
||
* Populated during `derive_extraction_result` before tree derivation consumes
|
||
* element data. `apply_output_format` swaps this into `content` at the end
|
||
* of the pipeline, after post-processors have operated on plain text.
|
||
*
|
||
* @var ?string
|
||
*/
|
||
public readonly ?string $formattedContent = null,
|
||
/**
|
||
* Structured hOCR document for the OCR+layout pipeline.
|
||
*
|
||
* When tesseract produces hOCR output, the parsed `InternalDocument` carries
|
||
* paragraph structure with bounding boxes and confidence scores. The layout
|
||
* classification step enriches these elements before final rendering.
|
||
*
|
||
* @var ?string
|
||
*/
|
||
public readonly ?string $ocrInternalDocument = null
|
||
) { }
|
||
public static function fromOcr(OcrExtractionResult $ocr): ExtractionResult
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
}
|
||
|
||
/**
|
||
* A single file extracted from an archive.
|
||
*
|
||
* When archives (ZIP, TAR, 7Z, GZIP) are extracted with recursive extraction
|
||
* enabled, each processable file produces its own full `ExtractionResult`.
|
||
*/
|
||
final class ArchiveEntry
|
||
{
|
||
public function __construct(
|
||
/** @var string Archive-relative file path (e.g. "folder/document.pdf"). */
|
||
public readonly string $path,
|
||
/** @var string Detected MIME type of the file. */
|
||
public readonly string $mimeType,
|
||
/** @var ExtractionResult Full extraction result for this file. */
|
||
public readonly ExtractionResult $result
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* A non-fatal warning from a processing pipeline stage.
|
||
*
|
||
* Captures errors from optional features that don't prevent extraction
|
||
* but may indicate degraded results.
|
||
*/
|
||
final class ProcessingWarning
|
||
{
|
||
public function __construct(
|
||
/**
|
||
* The pipeline stage or feature that produced this warning
|
||
* (e.g., "embedding", "chunking", "language_detection", "output_format").
|
||
*
|
||
* @var string
|
||
*/
|
||
public readonly string $source,
|
||
/** @var string Human-readable description of what went wrong. */
|
||
public readonly string $message
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Token usage and cost data for a single LLM call made during extraction.
|
||
*
|
||
* Populated when VLM OCR, structured extraction, or LLM-based embeddings
|
||
* are used. Multiple entries may be present when multiple LLM calls occur
|
||
* within one extraction (e.g. VLM OCR + structured extraction).
|
||
*/
|
||
final class LlmUsage
|
||
{
|
||
public function __construct(
|
||
/** @var string The LLM model identifier (e.g. "openai/gpt-4o", "anthropic/claude-sonnet-4-20250514"). */
|
||
public readonly string $model,
|
||
/**
|
||
* The pipeline stage that triggered this LLM call
|
||
* (e.g. "vlm_ocr", "structured_extraction", "embeddings").
|
||
*
|
||
* @var string
|
||
*/
|
||
public readonly string $source,
|
||
/** @var ?int Number of input/prompt tokens consumed. */
|
||
public readonly ?int $inputTokens = null,
|
||
/** @var ?int Number of output/completion tokens generated. */
|
||
public readonly ?int $outputTokens = null,
|
||
/** @var ?int Total tokens (input + output). */
|
||
public readonly ?int $totalTokens = null,
|
||
/** @var ?float Estimated cost in USD based on the provider's published pricing. */
|
||
public readonly ?float $estimatedCost = null,
|
||
/** @var ?string Why the model stopped generating (e.g. "stop", "length", "content_filter"). */
|
||
public readonly ?string $finishReason = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* A text chunk with optional embedding and metadata.
|
||
*
|
||
* Chunks are created when chunking is enabled in `ExtractionConfig`. Each chunk
|
||
* contains the text content, optional embedding vector (if embedding generation
|
||
* is configured), and metadata about its position in the document.
|
||
*/
|
||
final class Chunk
|
||
{
|
||
public function __construct(
|
||
/** @var string The text content of this chunk. */
|
||
public readonly string $content,
|
||
/**
|
||
* Semantic structural classification of this chunk.
|
||
*
|
||
* Assigned by the heuristic classifier based on content patterns and
|
||
* heading context. Defaults to `ChunkType::Unknown` when no rule matches.
|
||
*
|
||
* @var ChunkType
|
||
*/
|
||
public readonly ChunkType $chunkType,
|
||
/** @var ChunkMetadata Metadata about this chunk's position and properties. */
|
||
public readonly ChunkMetadata $metadata,
|
||
/**
|
||
* Optional embedding vector for this chunk.
|
||
*
|
||
* Only populated when `EmbeddingConfig` is provided in chunking configuration.
|
||
* The dimensionality depends on the chosen embedding model.
|
||
*
|
||
* @var ?array<float>
|
||
*/
|
||
public readonly ?array $embedding = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Heading context for a chunk within a Markdown document.
|
||
*
|
||
* Contains the heading hierarchy from document root to this chunk's section.
|
||
*/
|
||
final class HeadingContext
|
||
{
|
||
public function __construct(
|
||
/**
|
||
* The heading hierarchy from document root to this chunk's section.
|
||
* Index 0 is the outermost (h1), last element is the most specific.
|
||
*
|
||
* @var array<HeadingLevel>
|
||
*/
|
||
public readonly array $headings
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* A single heading in the hierarchy.
|
||
*/
|
||
final class HeadingLevel
|
||
{
|
||
public function __construct(
|
||
/** @var int Heading depth (1 = h1, 2 = h2, etc.) */
|
||
public readonly int $level,
|
||
/** @var string The text content of the heading. */
|
||
public readonly string $text
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Metadata about a chunk's position in the original document.
|
||
*/
|
||
final class ChunkMetadata
|
||
{
|
||
public function __construct(
|
||
/** @var int Byte offset where this chunk starts in the original text (UTF-8 valid boundary). */
|
||
public readonly int $byteStart,
|
||
/** @var int Byte offset where this chunk ends in the original text (UTF-8 valid boundary). */
|
||
public readonly int $byteEnd,
|
||
/** @var int Zero-based index of this chunk in the document. */
|
||
public readonly int $chunkIndex,
|
||
/** @var int Total number of chunks in the document. */
|
||
public readonly int $totalChunks,
|
||
/**
|
||
* Indices into `ExtractionResult.images` for images on pages covered by this chunk.
|
||
*
|
||
* Contains zero-based indices into the top-level `images` collection for every
|
||
* image whose `page_number` falls within `[first_page, last_page]`.
|
||
* Empty when image extraction is disabled or the chunk spans no pages with images.
|
||
*
|
||
* @var array<int>
|
||
*/
|
||
public readonly array $imageIndices,
|
||
/**
|
||
* Number of tokens in this chunk (if available).
|
||
*
|
||
* This is calculated by the embedding model's tokenizer if embeddings are enabled.
|
||
*
|
||
* @var ?int
|
||
*/
|
||
public readonly ?int $tokenCount = null,
|
||
/**
|
||
* First page number this chunk spans (1-indexed).
|
||
*
|
||
* Only populated when page tracking is enabled in extraction configuration.
|
||
*
|
||
* @var ?int
|
||
*/
|
||
public readonly ?int $firstPage = null,
|
||
/**
|
||
* Last page number this chunk spans (1-indexed, equal to first_page for single-page chunks).
|
||
*
|
||
* Only populated when page tracking is enabled in extraction configuration.
|
||
*
|
||
* @var ?int
|
||
*/
|
||
public readonly ?int $lastPage = null,
|
||
/**
|
||
* Heading context when using Markdown chunker.
|
||
*
|
||
* Contains the heading hierarchy this chunk falls under.
|
||
* Only populated when `ChunkerType::Markdown` is used.
|
||
*
|
||
* @var ?HeadingContext
|
||
*/
|
||
public readonly ?HeadingContext $headingContext = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Extracted image from a document.
|
||
*
|
||
* Contains raw image data, metadata, and optional nested OCR results.
|
||
* Raw bytes allow cross-language compatibility - users can convert to
|
||
* PIL.Image (Python), Sharp (Node.js), or other formats as needed.
|
||
*/
|
||
final class ExtractedImage
|
||
{
|
||
public function __construct(
|
||
/**
|
||
* Raw image data (PNG, JPEG, WebP, etc. bytes).
|
||
* Uses `bytes::Bytes` for cheap cloning of large buffers.
|
||
*
|
||
* @var string
|
||
*/
|
||
public readonly string $data,
|
||
/**
|
||
* Image format (e.g., "jpeg", "png", "webp")
|
||
* Uses Cow<'static, str> to avoid allocation for static literals.
|
||
*
|
||
* @var string
|
||
*/
|
||
public readonly string $format,
|
||
/** @var int Zero-indexed position of this image in the document/page */
|
||
public readonly int $imageIndex,
|
||
/** @var bool Whether this image is a mask image */
|
||
public readonly bool $isMask,
|
||
/** @var ?int Page/slide number where image was found (1-indexed) */
|
||
public readonly ?int $pageNumber = null,
|
||
/** @var ?int Image width in pixels */
|
||
public readonly ?int $width = null,
|
||
/** @var ?int Image height in pixels */
|
||
public readonly ?int $height = null,
|
||
/** @var ?string Colorspace information (e.g., "RGB", "CMYK", "Gray") */
|
||
public readonly ?string $colorspace = null,
|
||
/** @var ?int Bits per color component (e.g., 8, 16) */
|
||
public readonly ?int $bitsPerComponent = null,
|
||
/** @var ?string Optional description of the image */
|
||
public readonly ?string $description = null,
|
||
/**
|
||
* Nested OCR extraction result (if image was OCRed)
|
||
*
|
||
* When OCR is performed on this image, the result is embedded here
|
||
* rather than in a separate collection, making the relationship explicit.
|
||
*
|
||
* @var ?ExtractionResult
|
||
*/
|
||
public readonly ?ExtractionResult $ocrResult = null,
|
||
/**
|
||
* Bounding box of the image on the page (PDF coordinates: x0=left, y0=bottom, x1=right, y1=top).
|
||
* Only populated for PDF-extracted images when position data is available from the PDF extractor.
|
||
*
|
||
* @var ?BoundingBox
|
||
*/
|
||
public readonly ?BoundingBox $boundingBox = null,
|
||
/**
|
||
* Original source path of the image within the document archive (e.g., "media/image1.png" in DOCX).
|
||
* Used for rendering image references when the binary data is not extracted.
|
||
*
|
||
* @var ?string
|
||
*/
|
||
public readonly ?string $sourcePath = null,
|
||
/**
|
||
* Heuristic classification of what this image likely depicts.
|
||
* `None` if classification was disabled or inconclusive.
|
||
*
|
||
* @var ?ImageKind
|
||
*/
|
||
public readonly ?ImageKind $imageKind = null,
|
||
/** @var ?float Confidence score for `image_kind`, in the range 0.0 to 1.0. */
|
||
public readonly ?float $kindConfidence = null,
|
||
/**
|
||
* Identifier shared across images that form a single logical figure
|
||
* (e.g. all raster tiles of one technical drawing). `None` for singletons.
|
||
*
|
||
* @var ?int
|
||
*/
|
||
public readonly ?int $clusterId = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Bounding box coordinates for element positioning.
|
||
*/
|
||
final class BoundingBox
|
||
{
|
||
public function __construct(
|
||
/** @var float Left x-coordinate */
|
||
public readonly float $x0,
|
||
/** @var float Bottom y-coordinate */
|
||
public readonly float $y0,
|
||
/** @var float Right x-coordinate */
|
||
public readonly float $x1,
|
||
/** @var float Top y-coordinate */
|
||
public readonly float $y1
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Metadata for a semantic element.
|
||
*/
|
||
final class ElementMetadata
|
||
{
|
||
public function __construct(
|
||
/** @var array<string, string> Additional custom metadata */
|
||
public readonly array $additional,
|
||
/** @var ?int Page number (1-indexed) */
|
||
public readonly ?int $pageNumber = null,
|
||
/** @var ?string Source filename or document name */
|
||
public readonly ?string $filename = null,
|
||
/** @var ?BoundingBox Bounding box coordinates if available */
|
||
public readonly ?BoundingBox $coordinates = null,
|
||
/** @var ?int Position index in the element sequence */
|
||
public readonly ?int $elementIndex = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Semantic element extracted from document.
|
||
*
|
||
* Represents a logical unit of content with semantic classification,
|
||
* unique identifier, and metadata for tracking origin and position.
|
||
*/
|
||
final class Element
|
||
{
|
||
public function __construct(
|
||
/** @var string Unique element identifier */
|
||
public readonly string $elementId,
|
||
/** @var ElementType Semantic type of this element */
|
||
public readonly ElementType $elementType,
|
||
/** @var string Text content of the element */
|
||
public readonly string $text,
|
||
/** @var ElementMetadata Metadata about the element */
|
||
public readonly ElementMetadata $metadata
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Excel workbook representation.
|
||
*
|
||
* Contains all sheets from an Excel file (.xlsx, .xls, etc.) with
|
||
* extracted content and metadata.
|
||
*/
|
||
final class ExcelWorkbook
|
||
{
|
||
public function __construct(
|
||
/** @var array<ExcelSheet> All sheets in the workbook */
|
||
public readonly array $sheets,
|
||
/** @var array<string, string> Workbook-level metadata (author, creation date, etc.) */
|
||
public readonly array $metadata,
|
||
/**
|
||
* Collaborative-edit revision headers from `xl/revisions/revisionHeaders.xml`.
|
||
*
|
||
* Populated for legacy shared-workbook `.xlsx` files that contain the
|
||
* `xl/revisions/` directory. Each `<header>` element maps to one
|
||
* `DocumentRevision { kind: FormatChange }` carrying the header's `guid`
|
||
* (→ `revision_id`), `userName` (→ `author`), and `dateTime` (→ `timestamp`).
|
||
* `anchor` and `delta` are `None`/empty for v1 (per-cell log parsing is a
|
||
* follow-up). `None` when `xl/revisions/revisionHeaders.xml` is absent.
|
||
*
|
||
* @var ?array<DocumentRevision>
|
||
*/
|
||
public readonly ?array $revisions = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Single Excel worksheet.
|
||
*
|
||
* Represents one sheet from an Excel workbook with its content
|
||
* converted to Markdown format and dimensional statistics.
|
||
*/
|
||
final class ExcelSheet
|
||
{
|
||
public function __construct(
|
||
/** @var string Sheet name as it appears in Excel */
|
||
public readonly string $name,
|
||
/** @var string Sheet content converted to Markdown tables */
|
||
public readonly string $markdown,
|
||
/** @var int Number of rows */
|
||
public readonly int $rowCount,
|
||
/** @var int Number of columns */
|
||
public readonly int $colCount,
|
||
/** @var int Total number of non-empty cells */
|
||
public readonly int $cellCount,
|
||
/**
|
||
* Pre-extracted table cells (2D vector of cell values)
|
||
* Populated during markdown generation to avoid re-parsing markdown.
|
||
* None for empty sheets.
|
||
*
|
||
* @var ?array<array<string>>
|
||
*/
|
||
public readonly ?array $tableCells = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* XML extraction result.
|
||
*
|
||
* Contains extracted text content from XML files along with
|
||
* structural statistics about the XML document.
|
||
*/
|
||
final class XmlExtractionResult
|
||
{
|
||
public function __construct(
|
||
/** @var string Extracted text content (XML structure filtered out) */
|
||
public readonly string $content,
|
||
/** @var int Total number of XML elements processed */
|
||
public readonly int $elementCount,
|
||
/** @var array<string> List of unique element names found (sorted) */
|
||
public readonly array $uniqueElements
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Plain text and Markdown extraction result.
|
||
*
|
||
* Contains the extracted text along with statistics and,
|
||
* for Markdown files, structural elements like headers and links.
|
||
*/
|
||
final class TextExtractionResult
|
||
{
|
||
public function __construct(
|
||
/** @var string Extracted text content */
|
||
public readonly string $content,
|
||
/** @var int Number of lines */
|
||
public readonly int $lineCount,
|
||
/** @var int Number of words */
|
||
public readonly int $wordCount,
|
||
/** @var int Number of characters */
|
||
public readonly int $characterCount,
|
||
/** @var ?array<string> Markdown headers (text only, Markdown files only) */
|
||
public readonly ?array $headers = null,
|
||
/** @var ?array<array<string>> Markdown links as (text, URL) tuples (Markdown files only) */
|
||
public readonly ?array $links = null,
|
||
/** @var ?array<array<string>> Code blocks as (language, code) tuples (Markdown files only) */
|
||
public readonly ?array $codeBlocks = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* PowerPoint (PPTX) extraction result.
|
||
*
|
||
* Contains extracted slide content, metadata, and embedded images/tables.
|
||
*/
|
||
final class PptxExtractionResult
|
||
{
|
||
public function __construct(
|
||
/** @var string Extracted text content from all slides */
|
||
public readonly string $content,
|
||
/** @var PptxMetadata Presentation metadata */
|
||
public readonly PptxMetadata $metadata,
|
||
/** @var int Total number of slides */
|
||
public readonly int $slideCount,
|
||
/** @var int Total number of embedded images */
|
||
public readonly int $imageCount,
|
||
/** @var int Total number of tables */
|
||
public readonly int $tableCount,
|
||
/** @var array<ExtractedImage> Extracted images from the presentation */
|
||
public readonly array $images,
|
||
/** @var array<string> Hyperlinks discovered in slides as (url, optional_label) pairs. */
|
||
public readonly array $hyperlinks,
|
||
/**
|
||
* Office metadata extracted from docProps/core.xml and docProps/app.xml.
|
||
*
|
||
* Contains keys like "title", "author", "created_by", "subject", "keywords",
|
||
* "modified_by", "created_at", "modified_at", etc.
|
||
*
|
||
* @var array<string, string>
|
||
*/
|
||
public readonly array $officeMetadata,
|
||
/** @var ?PageStructure Slide structure with boundaries (when page tracking is enabled) */
|
||
public readonly ?PageStructure $pageStructure = null,
|
||
/** @var ?array<PageContent> Per-slide content (when page tracking is enabled) */
|
||
public readonly ?array $pageContents = null,
|
||
/** @var ?DocumentStructure Structured document representation */
|
||
public readonly ?DocumentStructure $document = null,
|
||
/**
|
||
* Slide comments as revisions.
|
||
*
|
||
* Each `<p:cm>` element in `ppt/comments/comment{N}.xml` becomes a
|
||
* `DocumentRevision { kind: Comment }` with author (resolved from
|
||
* `ppt/commentAuthors.xml`), ISO-8601 timestamp, and
|
||
* `RevisionAnchor::Slide { index }`. `None` when no comment XML parts exist.
|
||
*
|
||
* @var ?array<DocumentRevision>
|
||
*/
|
||
public readonly ?array $revisions = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Email extraction result.
|
||
*
|
||
* Complete representation of an extracted email message (.eml or .msg)
|
||
* including headers, body content, and attachments.
|
||
*/
|
||
final class EmailExtractionResult
|
||
{
|
||
public function __construct(
|
||
/** @var array<string> Primary recipient email addresses */
|
||
public readonly array $toEmails,
|
||
/** @var array<string> CC recipient email addresses */
|
||
public readonly array $ccEmails,
|
||
/** @var array<string> BCC recipient email addresses */
|
||
public readonly array $bccEmails,
|
||
/** @var string Cleaned/processed text content. Aliased as `cleaned_text` for back-compat. */
|
||
public readonly string $content,
|
||
/** @var array<EmailAttachment> List of email attachments */
|
||
public readonly array $attachments,
|
||
/** @var array<string, string> Additional email headers and metadata */
|
||
public readonly array $metadata,
|
||
/** @var ?string Email subject line */
|
||
public readonly ?string $subject = null,
|
||
/** @var ?string Sender email address */
|
||
public readonly ?string $fromEmail = null,
|
||
/** @var ?string Email date/timestamp */
|
||
public readonly ?string $date = null,
|
||
/** @var ?string Message-ID header value */
|
||
public readonly ?string $messageId = null,
|
||
/** @var ?string Plain text version of the email body */
|
||
public readonly ?string $plainText = null,
|
||
/** @var ?string HTML version of the email body */
|
||
public readonly ?string $htmlContent = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Email attachment representation.
|
||
*
|
||
* Contains metadata and optionally the content of an email attachment.
|
||
*/
|
||
final class EmailAttachment
|
||
{
|
||
public function __construct(
|
||
/** @var bool Whether this attachment is an image */
|
||
public readonly bool $isImage,
|
||
/** @var ?string Attachment name (from Content-Disposition header) */
|
||
public readonly ?string $name = null,
|
||
/** @var ?string Filename of the attachment */
|
||
public readonly ?string $filename = null,
|
||
/** @var ?string MIME type of the attachment */
|
||
public readonly ?string $mimeType = null,
|
||
/** @var ?int Size in bytes */
|
||
public readonly ?int $size = null,
|
||
/**
|
||
* Attachment data (if extracted).
|
||
* Uses `bytes::Bytes` for cheap cloning of large buffers.
|
||
*
|
||
* @var ?string
|
||
*/
|
||
public readonly ?string $data = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* OCR extraction result.
|
||
*
|
||
* Result of performing OCR on an image or scanned document,
|
||
* including recognized text and detected tables.
|
||
*/
|
||
final class OcrExtractionResult
|
||
{
|
||
public function __construct(
|
||
/** @var string Recognized text content */
|
||
public readonly string $content,
|
||
/** @var string Original MIME type of the processed image */
|
||
public readonly string $mimeType,
|
||
/** @var array<string, string> OCR processing metadata (confidence scores, language, etc.) */
|
||
public readonly array $metadata,
|
||
/** @var array<OcrTable> Tables detected and extracted via OCR */
|
||
public readonly array $tables,
|
||
/**
|
||
* Structured OCR elements with bounding boxes and confidence scores.
|
||
* Available when TSV output is requested or table detection is enabled.
|
||
*
|
||
* @var ?array<OcrElement>
|
||
*/
|
||
public readonly ?array $ocrElements = null,
|
||
/**
|
||
* Structured document produced from hOCR parsing.
|
||
* Carries paragraph structure, bounding boxes, and confidence scores
|
||
* that the flattened `content` string discards.
|
||
*
|
||
* @var ?string
|
||
*/
|
||
public readonly ?string $internalDocument = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Table detected via OCR.
|
||
*
|
||
* Represents a table structure recognized during OCR processing.
|
||
*/
|
||
final class OcrTable
|
||
{
|
||
public function __construct(
|
||
/** @var array<array<string>> Table cells as a 2D vector (rows × columns) */
|
||
public readonly array $cells,
|
||
/** @var string Markdown representation of the table */
|
||
public readonly string $markdown,
|
||
/** @var int Page number where the table was found (1-indexed) */
|
||
public readonly int $pageNumber,
|
||
/** @var ?OcrTableBoundingBox Bounding box of the table in pixel coordinates (from OCR word positions). */
|
||
public readonly ?OcrTableBoundingBox $boundingBox = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Bounding box for an OCR-detected table in pixel coordinates.
|
||
*/
|
||
final class OcrTableBoundingBox
|
||
{
|
||
public function __construct(
|
||
/** @var int Left x-coordinate (pixels) */
|
||
public readonly int $left,
|
||
/** @var int Top y-coordinate (pixels) */
|
||
public readonly int $top,
|
||
/** @var int Right x-coordinate (pixels) */
|
||
public readonly int $right,
|
||
/** @var int Bottom y-coordinate (pixels) */
|
||
public readonly int $bottom
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Image preprocessing configuration for OCR.
|
||
*
|
||
* These settings control how images are preprocessed before OCR to improve
|
||
* text recognition quality. Different preprocessing strategies work better
|
||
* for different document types.
|
||
*/
|
||
final class ImagePreprocessingConfig
|
||
{
|
||
public function __construct(
|
||
/** @var int Target DPI for the image (300 is standard, 600 for small text). */
|
||
public readonly int $targetDpi,
|
||
/** @var bool Auto-detect and correct image rotation. */
|
||
public readonly bool $autoRotate,
|
||
/** @var bool Correct skew (tilted images). */
|
||
public readonly bool $deskew,
|
||
/** @var bool Remove noise from the image. */
|
||
public readonly bool $denoise,
|
||
/** @var bool Enhance contrast for better text visibility. */
|
||
public readonly bool $contrastEnhance,
|
||
/** @var string Binarization method: "otsu", "sauvola", "adaptive". */
|
||
public readonly string $binarizationMethod,
|
||
/** @var bool Invert colors (white text on black → black on white). */
|
||
public readonly bool $invertColors
|
||
) { }
|
||
public static function default(): ImagePreprocessingConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
}
|
||
|
||
/**
|
||
* Tesseract OCR configuration.
|
||
*
|
||
* Provides fine-grained control over Tesseract OCR engine parameters.
|
||
* Most users can use the defaults, but these settings allow optimization
|
||
* for specific document types (invoices, handwriting, etc.).
|
||
*/
|
||
final class TesseractConfig
|
||
{
|
||
public function __construct(
|
||
/** @var string Language code (e.g., "eng", "deu", "fra") */
|
||
public readonly string $language,
|
||
/**
|
||
* Page Segmentation Mode (0-13).
|
||
*
|
||
* Common values:
|
||
* - 3: Fully automatic page segmentation (native default)
|
||
* - 6: Assume a single uniform block of text (WASM default — avoids layout-analysis hang)
|
||
* - 11: Sparse text with no particular order
|
||
*
|
||
* @var int
|
||
*/
|
||
public readonly int $psm,
|
||
/** @var string Output format ("text" or "markdown") */
|
||
public readonly string $outputFormat,
|
||
/**
|
||
* OCR Engine Mode (0-3).
|
||
*
|
||
* - 0: Legacy engine only
|
||
* - 1: Neural nets (LSTM) only (usually best)
|
||
* - 2: Legacy + LSTM
|
||
* - 3: Default (based on what's available)
|
||
*
|
||
* @var int
|
||
*/
|
||
public readonly int $oem,
|
||
/**
|
||
* Minimum confidence threshold (0.0-100.0).
|
||
*
|
||
* Words with confidence below this threshold may be rejected or flagged.
|
||
*
|
||
* @var float
|
||
*/
|
||
public readonly float $minConfidence,
|
||
/** @var bool Enable automatic table detection and reconstruction */
|
||
public readonly bool $enableTableDetection,
|
||
/** @var float Minimum confidence threshold for table detection (0.0-1.0) */
|
||
public readonly float $tableMinConfidence,
|
||
/** @var int Column threshold for table detection (pixels) */
|
||
public readonly int $tableColumnThreshold,
|
||
/** @var float Row threshold ratio for table detection (0.0-1.0) */
|
||
public readonly float $tableRowThresholdRatio,
|
||
/** @var bool Enable OCR result caching */
|
||
public readonly bool $useCache,
|
||
/** @var bool Use pre-adapted templates for character classification */
|
||
public readonly bool $classifyUsePreAdaptedTemplates,
|
||
/** @var bool Enable N-gram language model */
|
||
public readonly bool $languageModelNgramOn,
|
||
/** @var bool Don't reject good words during block-level processing */
|
||
public readonly bool $tesseditDontBlkrejGoodWds,
|
||
/** @var bool Don't reject good words during row-level processing */
|
||
public readonly bool $tesseditDontRowrejGoodWds,
|
||
/** @var bool Enable dictionary correction */
|
||
public readonly bool $tesseditEnableDictCorrection,
|
||
/** @var string Whitelist of allowed characters (empty = all allowed) */
|
||
public readonly string $tesseditCharWhitelist,
|
||
/** @var string Blacklist of forbidden characters (empty = none forbidden) */
|
||
public readonly string $tesseditCharBlacklist,
|
||
/** @var bool Use primary language params model */
|
||
public readonly bool $tesseditUsePrimaryParamsModel,
|
||
/** @var bool Variable-width space detection */
|
||
public readonly bool $textordSpaceSizeIsVariable,
|
||
/** @var bool Use adaptive thresholding method */
|
||
public readonly bool $thresholdingMethod,
|
||
/**
|
||
* Image preprocessing configuration.
|
||
*
|
||
* Controls how images are preprocessed before OCR. Can significantly
|
||
* improve quality for scanned documents or low-quality images.
|
||
*
|
||
* @var ?ImagePreprocessingConfig
|
||
*/
|
||
public readonly ?ImagePreprocessingConfig $preprocessing = null
|
||
) { }
|
||
public static function default(): TesseractConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
}
|
||
|
||
/**
|
||
* Image preprocessing metadata.
|
||
*
|
||
* Tracks the transformations applied to an image during OCR preprocessing,
|
||
* including DPI normalization, resizing, and resampling.
|
||
*/
|
||
final class ImagePreprocessingMetadata
|
||
{
|
||
public function __construct(
|
||
/** @var array<int> Original image dimensions (width, height) in pixels */
|
||
public readonly array $originalDimensions,
|
||
/** @var array<float> Original image DPI (horizontal, vertical) */
|
||
public readonly array $originalDpi,
|
||
/** @var int Target DPI from configuration */
|
||
public readonly int $targetDpi,
|
||
/** @var float Scaling factor applied to the image */
|
||
public readonly float $scaleFactor,
|
||
/** @var bool Whether DPI was auto-adjusted based on content */
|
||
public readonly bool $autoAdjusted,
|
||
/** @var int Final DPI after processing */
|
||
public readonly int $finalDpi,
|
||
/** @var string Resampling algorithm used ("LANCZOS3", "CATMULLROM", etc.) */
|
||
public readonly string $resampleMethod,
|
||
/** @var bool Whether dimensions were clamped to max_image_dimension */
|
||
public readonly bool $dimensionClamped,
|
||
/** @var bool Whether resize was skipped (dimensions already optimal) */
|
||
public readonly bool $skippedResize,
|
||
/** @var ?array<int> New dimensions after resizing (if resized) */
|
||
public readonly ?array $newDimensions = null,
|
||
/** @var ?int Calculated optimal DPI (if auto_adjust_dpi enabled) */
|
||
public readonly ?int $calculatedDpi = null,
|
||
/** @var ?string Error message if resize failed */
|
||
public readonly ?string $resizeError = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Extraction result metadata.
|
||
*
|
||
* Contains common fields applicable to all formats, format-specific metadata
|
||
* via a discriminated union, and additional custom fields from postprocessors.
|
||
*/
|
||
final class Metadata
|
||
{
|
||
public function __construct(
|
||
/**
|
||
* Whether OCR was used during extraction.
|
||
*
|
||
* Set to `true` whenever the extraction pipeline ran an OCR backend
|
||
* (Tesseract, PaddleOCR, VLM, etc.) and used that output as the primary
|
||
* or fallback text. `false` means native text extraction was used exclusively.
|
||
*
|
||
* @var bool
|
||
*/
|
||
public readonly bool $ocrUsed,
|
||
/**
|
||
* Additional custom fields from postprocessors.
|
||
*
|
||
* Serialized as a nested `"additional"` object (not flattened at root level).
|
||
* Uses `Cow<'static, str>` keys so static string keys avoid allocation.
|
||
*
|
||
* @var array<string, string>
|
||
*/
|
||
public readonly array $additional,
|
||
/** @var ?string Document title */
|
||
public readonly ?string $title = null,
|
||
/** @var ?string Document subject or description */
|
||
public readonly ?string $subject = null,
|
||
/** @var ?array<string> Primary author(s) - always Vec for consistency */
|
||
public readonly ?array $authors = null,
|
||
/** @var ?array<string> Keywords/tags - always Vec for consistency */
|
||
public readonly ?array $keywords = null,
|
||
/** @var ?string Primary language (ISO 639 code) */
|
||
public readonly ?string $language = null,
|
||
/** @var ?string Creation timestamp (ISO 8601 format) */
|
||
public readonly ?string $createdAt = null,
|
||
/** @var ?string Last modification timestamp (ISO 8601 format) */
|
||
public readonly ?string $modifiedAt = null,
|
||
/** @var ?string User who created the document */
|
||
public readonly ?string $createdBy = null,
|
||
/** @var ?string User who last modified the document */
|
||
public readonly ?string $modifiedBy = null,
|
||
/** @var ?PageStructure Page/slide/sheet structure with boundaries */
|
||
public readonly ?PageStructure $pages = null,
|
||
/**
|
||
* Format-specific metadata (discriminated union)
|
||
*
|
||
* Contains detailed metadata specific to the document format.
|
||
* Serialized as a nested `"format"` object with a `format_type` discriminator field.
|
||
*
|
||
* @var ?FormatMetadata
|
||
*/
|
||
public readonly ?FormatMetadata $format = null,
|
||
/** @var ?ImagePreprocessingMetadata Image preprocessing metadata (when OCR preprocessing was applied) */
|
||
public readonly ?ImagePreprocessingMetadata $imagePreprocessing = null,
|
||
/** @var ?string JSON schema (for structured data extraction) */
|
||
public readonly ?string $jsonSchema = null,
|
||
/** @var ?ErrorMetadata Error metadata (for batch operations) */
|
||
public readonly ?ErrorMetadata $error = null,
|
||
/**
|
||
* Extraction duration in milliseconds (for benchmarking).
|
||
*
|
||
* This field is populated by batch extraction to provide per-file timing
|
||
* information. It's `None` for single-file extraction (which uses external timing).
|
||
*
|
||
* @var ?int
|
||
*/
|
||
public readonly ?int $extractionDurationMs = null,
|
||
/** @var ?string Document category (from frontmatter or classification). */
|
||
public readonly ?string $category = null,
|
||
/** @var ?array<string> Document tags (from frontmatter). */
|
||
public readonly ?array $tags = null,
|
||
/** @var ?string Document version string (from frontmatter). */
|
||
public readonly ?string $documentVersion = null,
|
||
/** @var ?string Abstract or summary text (from frontmatter). */
|
||
public readonly ?string $abstractText = null,
|
||
/**
|
||
* Output format identifier (e.g., "markdown", "html", "text").
|
||
*
|
||
* Set by the output format pipeline stage when format conversion is applied.
|
||
* Previously stored in `metadata.additional["output_format"]`.
|
||
*
|
||
* @var ?string
|
||
*/
|
||
public readonly ?string $outputFormat = null
|
||
) { }
|
||
public function isEmpty(): bool
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
}
|
||
|
||
/**
|
||
* Excel/spreadsheet format metadata.
|
||
*
|
||
* Identifies the document as a spreadsheet source via the `FormatMetadata.Excel`
|
||
* discriminant. Sheet count and sheet names are stored inside this struct.
|
||
*/
|
||
final class ExcelMetadata
|
||
{
|
||
public function __construct(
|
||
/** @var ?int Number of sheets in the workbook. */
|
||
public readonly ?int $sheetCount = null,
|
||
/** @var ?array<string> Names of all sheets in the workbook. */
|
||
public readonly ?array $sheetNames = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Email metadata extracted from .eml and .msg files.
|
||
*
|
||
* Includes sender/recipient information, message ID, and attachment list.
|
||
*/
|
||
final class EmailMetadata
|
||
{
|
||
public function __construct(
|
||
/** @var array<string> Primary recipients */
|
||
public readonly array $toEmails,
|
||
/** @var array<string> CC recipients */
|
||
public readonly array $ccEmails,
|
||
/** @var array<string> BCC recipients */
|
||
public readonly array $bccEmails,
|
||
/** @var array<string> List of attachment filenames */
|
||
public readonly array $attachments,
|
||
/** @var ?string Sender's email address */
|
||
public readonly ?string $fromEmail = null,
|
||
/** @var ?string Sender's display name */
|
||
public readonly ?string $fromName = null,
|
||
/** @var ?string Message-ID header value */
|
||
public readonly ?string $messageId = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Archive (ZIP/TAR/7Z) metadata.
|
||
*
|
||
* Extracted from compressed archive files containing file lists and size information.
|
||
*/
|
||
final class ArchiveMetadata
|
||
{
|
||
public function __construct(
|
||
/** @var string Archive format ("ZIP", "TAR", "7Z", etc.) */
|
||
public readonly string $format,
|
||
/** @var int Total number of files in the archive */
|
||
public readonly int $fileCount,
|
||
/** @var array<string> List of file paths within the archive */
|
||
public readonly array $fileList,
|
||
/** @var int Total uncompressed size in bytes */
|
||
public readonly int $totalSize,
|
||
/** @var ?int Compressed size in bytes (if available) */
|
||
public readonly ?int $compressedSize = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Image metadata extracted from image files.
|
||
*
|
||
* Includes dimensions, format, and EXIF data.
|
||
*/
|
||
final class ImageMetadata
|
||
{
|
||
public function __construct(
|
||
/** @var int Image width in pixels */
|
||
public readonly int $width,
|
||
/** @var int Image height in pixels */
|
||
public readonly int $height,
|
||
/** @var string Image format (e.g., "PNG", "JPEG", "TIFF") */
|
||
public readonly string $format,
|
||
/** @var array<string, string> EXIF metadata tags */
|
||
public readonly array $exif
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* XML metadata extracted during XML parsing.
|
||
*
|
||
* Provides statistics about XML document structure.
|
||
*/
|
||
final class XmlMetadata
|
||
{
|
||
public function __construct(
|
||
/** @var int Total number of XML elements processed */
|
||
public readonly int $elementCount,
|
||
/** @var array<string> List of unique element tag names (sorted) */
|
||
public readonly array $uniqueElements
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Text/Markdown metadata.
|
||
*
|
||
* Extracted from plain text and Markdown files. Includes word counts and,
|
||
* for Markdown, structural elements like headers and links.
|
||
*/
|
||
final class TextMetadata
|
||
{
|
||
public function __construct(
|
||
/** @var int Number of lines in the document */
|
||
public readonly int $lineCount,
|
||
/** @var int Number of words */
|
||
public readonly int $wordCount,
|
||
/** @var int Number of characters */
|
||
public readonly int $characterCount,
|
||
/** @var ?array<string> Markdown headers (headings text only, for Markdown files) */
|
||
public readonly ?array $headers = null,
|
||
/** @var ?array<array<string>> Markdown links as (text, url) tuples (for Markdown files) */
|
||
public readonly ?array $links = null,
|
||
/** @var ?array<array<string>> Code blocks as (language, code) tuples (for Markdown files) */
|
||
public readonly ?array $codeBlocks = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Header/heading element metadata.
|
||
*/
|
||
final class HeaderMetadata
|
||
{
|
||
public function __construct(
|
||
/** @var int Header level: 1 (h1) through 6 (h6) */
|
||
public readonly int $level,
|
||
/** @var string Normalized text content of the header */
|
||
public readonly string $text,
|
||
/** @var int Document tree depth at the header element */
|
||
public readonly int $depth,
|
||
/** @var int Byte offset in original HTML document */
|
||
public readonly int $htmlOffset,
|
||
/** @var ?string HTML id attribute if present */
|
||
public readonly ?string $id = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Link element metadata.
|
||
*/
|
||
final class LinkMetadata
|
||
{
|
||
public function __construct(
|
||
/** @var string The href URL value */
|
||
public readonly string $href,
|
||
/** @var string Link text content (normalized) */
|
||
public readonly string $text,
|
||
/** @var LinkType Link type classification */
|
||
public readonly LinkType $linkType,
|
||
/** @var array<string> Rel attribute values */
|
||
public readonly array $rel,
|
||
/** @var array<array<string>> Additional attributes as key-value pairs */
|
||
public readonly array $attributes,
|
||
/** @var ?string Optional title attribute */
|
||
public readonly ?string $title = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Image element metadata.
|
||
*/
|
||
final class ImageMetadataType
|
||
{
|
||
public function __construct(
|
||
/** @var string Image source (URL, data URI, or SVG content) */
|
||
public readonly string $src,
|
||
/** @var ImageType Image type classification */
|
||
public readonly ImageType $imageType,
|
||
/** @var array<array<string>> Additional attributes as key-value pairs */
|
||
public readonly array $attributes,
|
||
/** @var ?string Alternative text from alt attribute */
|
||
public readonly ?string $alt = null,
|
||
/** @var ?string Title attribute */
|
||
public readonly ?string $title = null,
|
||
/** @var ?array<int> Image dimensions as (width, height) if available */
|
||
public readonly ?array $dimensions = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Structured data (Schema.org, microdata, RDFa) block.
|
||
*/
|
||
final class StructuredData
|
||
{
|
||
public function __construct(
|
||
/** @var StructuredDataType Type of structured data */
|
||
public readonly StructuredDataType $dataType,
|
||
/** @var string Raw JSON string representation */
|
||
public readonly string $rawJson,
|
||
/** @var ?string Schema type if detectable (e.g., "Article", "Event", "Product") */
|
||
public readonly ?string $schemaType = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* HTML metadata extracted from HTML documents.
|
||
*
|
||
* Includes document-level metadata, Open Graph data, Twitter Card metadata,
|
||
* and extracted structural elements (headers, links, images, structured data).
|
||
*/
|
||
final class HtmlMetadata
|
||
{
|
||
public function __construct(
|
||
/** @var array<string> Document keywords from `<meta name="keywords">` tag, split on commas */
|
||
public readonly array $keywords,
|
||
/**
|
||
* Open Graph metadata (og:* properties) for social media
|
||
* Keys like "title", "description", "image", "url", etc.
|
||
*
|
||
* @var array<string, string>
|
||
*/
|
||
public readonly array $openGraph,
|
||
/**
|
||
* Twitter Card metadata (twitter:* properties)
|
||
* Keys like "card", "site", "creator", "title", "description", "image", etc.
|
||
*
|
||
* @var array<string, string>
|
||
*/
|
||
public readonly array $twitterCard,
|
||
/**
|
||
* Additional meta tags not covered by specific fields
|
||
* Keys are meta name/property attributes, values are content
|
||
*
|
||
* @var array<string, string>
|
||
*/
|
||
public readonly array $metaTags,
|
||
/** @var array<HeaderMetadata> Extracted header elements with hierarchy */
|
||
public readonly array $headers,
|
||
/** @var array<LinkMetadata> Extracted hyperlinks with type classification */
|
||
public readonly array $links,
|
||
/** @var array<ImageMetadataType> Extracted images with source and dimensions */
|
||
public readonly array $images,
|
||
/** @var array<StructuredData> Extracted structured data blocks */
|
||
public readonly array $structuredData,
|
||
/** @var ?string Document title from `<title>` tag */
|
||
public readonly ?string $title = null,
|
||
/** @var ?string Document description from `<meta name="description">` tag */
|
||
public readonly ?string $description = null,
|
||
/** @var ?string Document author from `<meta name="author">` tag */
|
||
public readonly ?string $author = null,
|
||
/** @var ?string Canonical URL from `<link rel="canonical">` tag */
|
||
public readonly ?string $canonicalUrl = null,
|
||
/** @var ?string Base URL from `<base href="">` tag for resolving relative URLs */
|
||
public readonly ?string $baseHref = null,
|
||
/** @var ?string Document language from `lang` attribute */
|
||
public readonly ?string $language = null,
|
||
/** @var ?TextDirection Document text direction from `dir` attribute */
|
||
public readonly ?TextDirection $textDirection = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* OCR processing metadata.
|
||
*
|
||
* Captures information about OCR processing configuration and results.
|
||
*/
|
||
final class OcrMetadata
|
||
{
|
||
public function __construct(
|
||
/** @var string OCR language code(s) used */
|
||
public readonly string $language,
|
||
/** @var int Tesseract Page Segmentation Mode (PSM) */
|
||
public readonly int $psm,
|
||
/** @var string Output format (e.g., "text", "hocr") */
|
||
public readonly string $outputFormat,
|
||
/** @var int Number of tables detected */
|
||
public readonly int $tableCount,
|
||
/** @var ?int */
|
||
public readonly ?int $tableRows = null,
|
||
/** @var ?int */
|
||
public readonly ?int $tableCols = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Error metadata (for batch operations).
|
||
*/
|
||
final class ErrorMetadata
|
||
{
|
||
public function __construct(
|
||
/** @var string */
|
||
public readonly string $errorType,
|
||
/** @var string */
|
||
public readonly string $message
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* PowerPoint presentation metadata.
|
||
*
|
||
* Extracted from PPTX files containing slide counts and presentation details.
|
||
*/
|
||
final class PptxMetadata
|
||
{
|
||
public function __construct(
|
||
/** @var int Total number of slides in the presentation */
|
||
public readonly int $slideCount,
|
||
/** @var array<string> Names of slides (if available) */
|
||
public readonly array $slideNames,
|
||
/** @var ?int Number of embedded images */
|
||
public readonly ?int $imageCount = null,
|
||
/** @var ?int Number of tables */
|
||
public readonly ?int $tableCount = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Word document metadata.
|
||
*
|
||
* Extracted from DOCX files using shared Office Open XML metadata extraction.
|
||
* Integrates with `office_metadata` module for core/app/custom properties.
|
||
*/
|
||
final class DocxMetadata
|
||
{
|
||
public function __construct(
|
||
/**
|
||
* Core properties from docProps/core.xml (Dublin Core metadata)
|
||
*
|
||
* Contains title, creator, subject, keywords, dates, etc.
|
||
* Shared format across DOCX/PPTX/XLSX documents.
|
||
*
|
||
* @var ?CoreProperties
|
||
*/
|
||
public readonly ?CoreProperties $coreProperties = null,
|
||
/**
|
||
* Application properties from docProps/app.xml (Word-specific statistics)
|
||
*
|
||
* Contains word count, page count, paragraph count, editing time, etc.
|
||
* DOCX-specific variant of Office application properties.
|
||
*
|
||
* @var ?DocxAppProperties
|
||
*/
|
||
public readonly ?DocxAppProperties $appProperties = null,
|
||
/**
|
||
* Custom properties from docProps/custom.xml (user-defined properties)
|
||
*
|
||
* Contains key-value pairs defined by users or applications.
|
||
* Values can be strings, numbers, booleans, or dates.
|
||
*
|
||
* @var ?array<string, string>
|
||
*/
|
||
public readonly ?array $customProperties = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* CSV/TSV file metadata.
|
||
*/
|
||
final class CsvMetadata
|
||
{
|
||
public function __construct(
|
||
/** @var int */
|
||
public readonly int $rowCount,
|
||
/** @var int */
|
||
public readonly int $columnCount,
|
||
/** @var bool */
|
||
public readonly bool $hasHeader,
|
||
/** @var ?string */
|
||
public readonly ?string $delimiter = null,
|
||
/** @var ?array<string> */
|
||
public readonly ?array $columnTypes = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* BibTeX bibliography metadata.
|
||
*/
|
||
final class BibtexMetadata
|
||
{
|
||
public function __construct(
|
||
/** @var int Number of entries in the bibliography. */
|
||
public readonly int $entryCount,
|
||
/** @var array<string> */
|
||
public readonly array $citationKeys,
|
||
/** @var array<string> */
|
||
public readonly array $authors,
|
||
/** @var ?YearRange */
|
||
public readonly ?YearRange $yearRange = null,
|
||
/** @var ?array<string, int> */
|
||
public readonly ?array $entryTypes = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Citation file metadata (RIS, PubMed, EndNote).
|
||
*/
|
||
final class CitationMetadata
|
||
{
|
||
public function __construct(
|
||
/** @var int */
|
||
public readonly int $citationCount,
|
||
/** @var array<string> */
|
||
public readonly array $authors,
|
||
/** @var array<string> */
|
||
public readonly array $dois,
|
||
/** @var array<string> */
|
||
public readonly array $keywords,
|
||
/** @var ?string */
|
||
public readonly ?string $format = null,
|
||
/** @var ?YearRange */
|
||
public readonly ?YearRange $yearRange = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Year range for bibliographic metadata.
|
||
*/
|
||
final class YearRange
|
||
{
|
||
public function __construct(
|
||
/** @var array<int> */
|
||
public readonly array $years,
|
||
/** @var ?int */
|
||
public readonly ?int $min = null,
|
||
/** @var ?int */
|
||
public readonly ?int $max = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* FictionBook (FB2) metadata.
|
||
*/
|
||
final class FictionBookMetadata
|
||
{
|
||
public function __construct(
|
||
/** @var array<string> */
|
||
public readonly array $genres,
|
||
/** @var array<string> */
|
||
public readonly array $sequences,
|
||
/** @var ?string */
|
||
public readonly ?string $annotation = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* dBASE (DBF) file metadata.
|
||
*/
|
||
final class DbfMetadata
|
||
{
|
||
public function __construct(
|
||
/** @var int */
|
||
public readonly int $recordCount,
|
||
/** @var int */
|
||
public readonly int $fieldCount,
|
||
/** @var array<DbfFieldInfo> */
|
||
public readonly array $fields
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* dBASE field information.
|
||
*/
|
||
final class DbfFieldInfo
|
||
{
|
||
public function __construct(
|
||
/** @var string */
|
||
public readonly string $name,
|
||
/** @var string */
|
||
public readonly string $fieldType
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* JATS (Journal Article Tag Suite) metadata.
|
||
*/
|
||
final class JatsMetadata
|
||
{
|
||
public function __construct(
|
||
/** @var array<string, string> */
|
||
public readonly array $historyDates,
|
||
/** @var array<ContributorRole> */
|
||
public readonly array $contributorRoles,
|
||
/** @var ?string */
|
||
public readonly ?string $copyright = null,
|
||
/** @var ?string */
|
||
public readonly ?string $license = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* JATS contributor with role.
|
||
*/
|
||
final class ContributorRole
|
||
{
|
||
public function __construct(
|
||
/** @var string */
|
||
public readonly string $name,
|
||
/** @var ?string */
|
||
public readonly ?string $role = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* EPUB metadata (Dublin Core extensions).
|
||
*/
|
||
final class EpubMetadata
|
||
{
|
||
public function __construct(
|
||
/** @var ?string */
|
||
public readonly ?string $coverage = null,
|
||
/** @var ?string */
|
||
public readonly ?string $dcFormat = null,
|
||
/** @var ?string */
|
||
public readonly ?string $relation = null,
|
||
/** @var ?string */
|
||
public readonly ?string $source = null,
|
||
/** @var ?string */
|
||
public readonly ?string $dcType = null,
|
||
/** @var ?string */
|
||
public readonly ?string $coverImage = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Outlook PST archive metadata.
|
||
*/
|
||
final class PstMetadata
|
||
{
|
||
public function __construct(
|
||
/** @var int */
|
||
public readonly int $messageCount
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Confidence scores for an OCR element.
|
||
*
|
||
* Separates detection confidence (how confident that text exists at this location)
|
||
* from recognition confidence (how confident about the actual text content).
|
||
*/
|
||
final class OcrConfidence
|
||
{
|
||
public function __construct(
|
||
/**
|
||
* Recognition confidence: how confident about the text content.
|
||
*
|
||
* Range: 0.0 to 1.0.
|
||
*
|
||
* @var float
|
||
*/
|
||
public readonly float $recognition,
|
||
/**
|
||
* Detection confidence: how confident the OCR engine is that text exists here.
|
||
*
|
||
* PaddleOCR provides this as `box_score`, Tesseract doesn't have a direct equivalent.
|
||
* Range: 0.0 to 1.0 (or None if not available).
|
||
*
|
||
* @var ?float
|
||
*/
|
||
public readonly ?float $detection = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Rotation information for an OCR element.
|
||
*/
|
||
final class OcrRotation
|
||
{
|
||
public function __construct(
|
||
/** @var float Rotation angle in degrees (0, 90, 180, 270 for PaddleOCR). */
|
||
public readonly float $angleDegrees,
|
||
/** @var ?float Confidence score for the rotation detection. */
|
||
public readonly ?float $confidence = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* A unified OCR element representing detected text with full metadata.
|
||
*
|
||
* This is the primary type for structured OCR output, preserving all information
|
||
* from both Tesseract and PaddleOCR backends.
|
||
*/
|
||
final class OcrElement
|
||
{
|
||
public function __construct(
|
||
/** @var string The recognized text content. */
|
||
public readonly string $text,
|
||
/** @var OcrBoundingGeometry Bounding geometry (rectangle or quadrilateral). */
|
||
public readonly OcrBoundingGeometry $geometry,
|
||
/** @var OcrConfidence Confidence scores for detection and recognition. */
|
||
public readonly OcrConfidence $confidence,
|
||
/** @var OcrElementLevel Hierarchical level (word, line, block, page). */
|
||
public readonly OcrElementLevel $level,
|
||
/** @var int Page number (1-indexed). */
|
||
public readonly int $pageNumber,
|
||
/** @var array<string, string> Backend-specific metadata that doesn't fit the unified schema. */
|
||
public readonly array $backendMetadata,
|
||
/** @var ?OcrRotation Rotation information (if detected). */
|
||
public readonly ?OcrRotation $rotation = null,
|
||
/**
|
||
* Parent element ID for hierarchical relationships.
|
||
*
|
||
* Only used for Tesseract output which has word -> line -> block hierarchy.
|
||
*
|
||
* @var ?string
|
||
*/
|
||
public readonly ?string $parentId = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Configuration for OCR element extraction.
|
||
*
|
||
* Controls how OCR elements are extracted and filtered.
|
||
*/
|
||
final class OcrElementConfig
|
||
{
|
||
public function __construct(
|
||
/**
|
||
* Whether to include OCR elements in the extraction result.
|
||
*
|
||
* When true, the `ocr_elements` field in `ExtractionResult` will be populated.
|
||
*
|
||
* @var bool
|
||
*/
|
||
public readonly bool $includeElements,
|
||
/**
|
||
* Minimum hierarchical level to include.
|
||
*
|
||
* Elements below this level (e.g., words when min_level is Line) will be excluded.
|
||
*
|
||
* @var OcrElementLevel
|
||
*/
|
||
public readonly OcrElementLevel $minLevel,
|
||
/**
|
||
* Minimum recognition confidence threshold (0.0-1.0).
|
||
*
|
||
* Elements with confidence below this threshold will be filtered out.
|
||
*
|
||
* @var float
|
||
*/
|
||
public readonly float $minConfidence,
|
||
/**
|
||
* Whether to build hierarchical relationships between elements.
|
||
*
|
||
* When true, `parent_id` fields will be populated based on spatial containment.
|
||
* Only meaningful for Tesseract output.
|
||
*
|
||
* @var bool
|
||
*/
|
||
public readonly bool $buildHierarchy
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Unified page structure for documents.
|
||
*
|
||
* Supports different page types (PDF pages, PPTX slides, Excel sheets)
|
||
* with character offset boundaries for chunk-to-page mapping.
|
||
*/
|
||
final class PageStructure
|
||
{
|
||
public function __construct(
|
||
/** @var int Total number of pages/slides/sheets */
|
||
public readonly int $totalCount,
|
||
/** @var PageUnitType Type of paginated unit */
|
||
public readonly PageUnitType $unitType,
|
||
/**
|
||
* Character offset boundaries for each page
|
||
*
|
||
* Maps character ranges in the extracted content to page numbers.
|
||
* Used for chunk page range calculation.
|
||
*
|
||
* @var ?array<PageBoundary>
|
||
*/
|
||
public readonly ?array $boundaries = null,
|
||
/** @var ?array<PageInfo> Detailed per-page metadata (optional, only when needed) */
|
||
public readonly ?array $pages = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Byte offset boundary for a page.
|
||
*
|
||
* Tracks where a specific page's content starts and ends in the main content string,
|
||
* enabling mapping from byte positions to page numbers. Offsets are guaranteed to be
|
||
* at valid UTF-8 character boundaries when using standard String methods (push_str, push, etc.).
|
||
*/
|
||
final class PageBoundary
|
||
{
|
||
public function __construct(
|
||
/** @var int Byte offset where this page starts in the content string (UTF-8 valid boundary, inclusive) */
|
||
public readonly int $byteStart,
|
||
/** @var int Byte offset where this page ends in the content string (UTF-8 valid boundary, exclusive) */
|
||
public readonly int $byteEnd,
|
||
/** @var int Page number (1-indexed) */
|
||
public readonly int $pageNumber
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Metadata for individual page/slide/sheet.
|
||
*
|
||
* Captures per-page information including dimensions, content counts,
|
||
* and visibility state (for presentations).
|
||
*/
|
||
final class PageInfo
|
||
{
|
||
public function __construct(
|
||
/** @var int Page number (1-indexed) */
|
||
public readonly int $number,
|
||
/**
|
||
* Whether this page contains non-trivial vector graphics (paths, shapes, curves)
|
||
*
|
||
* Indicates the presence of vector-drawn content such as charts, diagrams,
|
||
* or geometric shapes (e.g., from Adobe InDesign, LaTeX TikZ). These are
|
||
* invisible to `ExtractionResult.images` since they are not embedded as raster
|
||
* XObjects. Set to `true` when path count exceeds a heuristic threshold,
|
||
* signaling that downstream consumers may want to rasterize the page to
|
||
* capture this content.
|
||
*
|
||
* Only populated for PDFs; `None` for other document types.
|
||
*
|
||
* @var bool
|
||
*/
|
||
public readonly bool $hasVectorGraphics,
|
||
/** @var ?string Page title (usually for presentations) */
|
||
public readonly ?string $title = null,
|
||
/** @var ?array<float> Dimensions in points (PDF) or pixels (images): (width, height) */
|
||
public readonly ?array $dimensions = null,
|
||
/** @var ?int Number of images on this page */
|
||
public readonly ?int $imageCount = null,
|
||
/** @var ?int Number of tables on this page */
|
||
public readonly ?int $tableCount = null,
|
||
/** @var ?bool Whether this page is hidden (e.g., in presentations) */
|
||
public readonly ?bool $hidden = null,
|
||
/**
|
||
* Whether this page is blank (no meaningful text, no images, no tables)
|
||
*
|
||
* A page is considered blank if it has fewer than 3 non-whitespace characters
|
||
* and contains no tables or images. This is useful for filtering out empty pages
|
||
* in scanned documents or PDFs with blank separator pages.
|
||
*
|
||
* @var ?bool
|
||
*/
|
||
public readonly ?bool $isBlank = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Content for a single page/slide.
|
||
*
|
||
* When page extraction is enabled, documents are split into per-page content
|
||
* with associated tables and images mapped to each page.
|
||
*
|
||
* # Performance
|
||
*
|
||
* Uses Arc-wrapped tables and images for memory efficiency:
|
||
* - `Vec<Arc<Table>>` enables zero-copy sharing of table data
|
||
* - `Vec<Arc<ExtractedImage>>` enables zero-copy sharing of image data
|
||
* - Maintains exact JSON compatibility via custom Serialize/Deserialize
|
||
*
|
||
* This reduces memory overhead for documents with shared tables/images
|
||
* by avoiding redundant copies during serialization.
|
||
*/
|
||
final class PageContent
|
||
{
|
||
public function __construct(
|
||
/** @var int Page number (1-indexed) */
|
||
public readonly int $pageNumber,
|
||
/** @var string Text content for this page */
|
||
public readonly string $content,
|
||
/**
|
||
* Tables found on this page (uses Arc for memory efficiency)
|
||
*
|
||
* Serializes as Vec<Table> for JSON compatibility while maintaining
|
||
* Arc semantics in-memory for zero-copy sharing.
|
||
*
|
||
* @var array<Table>
|
||
*/
|
||
public readonly array $tables,
|
||
/**
|
||
* Indices into `ExtractionResult.images` for images found on this page.
|
||
*
|
||
* Each value is a zero-based index into the top-level `images` collection.
|
||
* Only populated when `extract_images = true` in the extraction config.
|
||
*
|
||
* @var array<int>
|
||
*/
|
||
public readonly array $imageIndices,
|
||
/**
|
||
* Hierarchy information for the page (when hierarchy extraction is enabled)
|
||
*
|
||
* Contains text hierarchy levels (H1-H6) extracted from the page content.
|
||
*
|
||
* @var ?PageHierarchy
|
||
*/
|
||
public readonly ?PageHierarchy $hierarchy = null,
|
||
/**
|
||
* Whether this page is blank (no meaningful text content)
|
||
*
|
||
* Determined during extraction based on text content analysis.
|
||
* A page is blank if it has fewer than 3 non-whitespace characters
|
||
* and contains no tables or images.
|
||
*
|
||
* @var ?bool
|
||
*/
|
||
public readonly ?bool $isBlank = null,
|
||
/**
|
||
* Layout detection regions for this page (when layout detection is enabled).
|
||
*
|
||
* Contains detected layout regions with class, confidence, bounding box,
|
||
* and area fraction. Only populated when layout detection is configured.
|
||
*
|
||
* @var ?array<LayoutRegion>
|
||
*/
|
||
public readonly ?array $layoutRegions = null,
|
||
/**
|
||
* Speaker notes for this slide (PPTX only).
|
||
*
|
||
* Contains the text from the slide's notes pane (`ppt/notesSlides/notesSlide{N}.xml`).
|
||
* Only populated when the source is a PPTX file and notes are present.
|
||
*
|
||
* @var ?string
|
||
*/
|
||
public readonly ?string $speakerNotes = null,
|
||
/**
|
||
* Section name this slide belongs to (PPTX only).
|
||
*
|
||
* PowerPoint sections group slides into logical chapters (`<p:sectionLst>` in
|
||
* `ppt/presentation.xml`). Only populated when the source is a PPTX file and
|
||
* the slide belongs to a named section.
|
||
*
|
||
* @var ?string
|
||
*/
|
||
public readonly ?string $sectionName = null,
|
||
/**
|
||
* Sheet name for this page (XLSX/ODS only).
|
||
*
|
||
* Each spreadsheet sheet maps to one `PageContent` entry. This field carries the
|
||
* sheet's display name as it appears in the workbook. `None` for all non-spreadsheet
|
||
* formats and for sheets with an empty name.
|
||
*
|
||
* @var ?string
|
||
*/
|
||
public readonly ?string $sheetName = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* A detected layout region on a page.
|
||
*
|
||
* When layout detection is enabled, each page may have layout regions
|
||
* identifying different content types (text, pictures, tables, etc.)
|
||
* with confidence scores and spatial positions.
|
||
*/
|
||
final class LayoutRegion
|
||
{
|
||
public function __construct(
|
||
/** @var string Layout class name (e.g. "picture", "table", "text", "section_header"). */
|
||
public readonly string $className,
|
||
/** @var float Confidence score from the layout detection model (0.0 to 1.0). */
|
||
public readonly float $confidence,
|
||
/** @var BoundingBox Bounding box in document coordinate space. */
|
||
public readonly BoundingBox $boundingBox,
|
||
/** @var float Fraction of the page area covered by this region (0.0 to 1.0). */
|
||
public readonly float $areaFraction
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Page hierarchy structure containing heading levels and block information.
|
||
*
|
||
* Used when PDF text hierarchy extraction is enabled. Contains hierarchical
|
||
* blocks with heading levels (H1-H6) for semantic document structure.
|
||
*/
|
||
final class PageHierarchy
|
||
{
|
||
public function __construct(
|
||
/** @var int Number of hierarchy blocks on this page */
|
||
public readonly int $blockCount,
|
||
/** @var array<HierarchicalBlock> Hierarchical blocks with heading levels */
|
||
public readonly array $blocks
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* A text block with hierarchy level assignment.
|
||
*
|
||
* Represents a block of text with semantic heading information extracted from
|
||
* font size clustering and hierarchical analysis.
|
||
*/
|
||
final class HierarchicalBlock
|
||
{
|
||
public function __construct(
|
||
/** @var string The text content of this block */
|
||
public readonly string $text,
|
||
/** @var float The font size of the text in this block */
|
||
public readonly float $fontSize,
|
||
/**
|
||
* The hierarchy level of this block (H1-H6 or Body)
|
||
*
|
||
* Levels correspond to HTML heading tags:
|
||
* - "h1": Top-level heading
|
||
* - "h2": Secondary heading
|
||
* - "h3": Tertiary heading
|
||
* - "h4": Quaternary heading
|
||
* - "h5": Quinary heading
|
||
* - "h6": Senary heading
|
||
* - "body": Body text (no heading level)
|
||
*
|
||
* @var string
|
||
*/
|
||
public readonly string $level,
|
||
/**
|
||
* Bounding box information for the block
|
||
*
|
||
* Contains coordinates as (left, top, right, bottom) in PDF units.
|
||
*
|
||
* @var ?array<float>
|
||
*/
|
||
public readonly ?array $bbox = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* A single changed cell within a table.
|
||
*
|
||
* Defined here (rather than only in `crate.diff`) so `RevisionDelta` can
|
||
* reference it unconditionally, without requiring the `diff` Cargo feature.
|
||
* `crate.diff` re-exports this type verbatim.
|
||
*/
|
||
final class CellChange
|
||
{
|
||
public function __construct(
|
||
/** @var int Zero-based row index. */
|
||
public readonly int $row,
|
||
/** @var int Zero-based column index. */
|
||
public readonly int $col,
|
||
/** @var string Value before the change. */
|
||
public readonly string $from,
|
||
/** @var string Value after the change. */
|
||
public readonly string $to
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* A single tracked change embedded in a document.
|
||
*
|
||
* Populated by per-format extractors that understand change-tracking metadata
|
||
* (DOCX `w:ins`/`w:del`/`w:rPrChange`, ODT `text:change-*`, …). Every
|
||
* extractor defaults to `ExtractionResult.revisions = None` until a
|
||
* format-specific implementation is added.
|
||
*/
|
||
final class DocumentRevision
|
||
{
|
||
public function __construct(
|
||
/**
|
||
* Format-specific revision identifier.
|
||
*
|
||
* For DOCX this is the `w:id` attribute value on the change element
|
||
* (e.g. `"42"`). When the attribute is absent a synthetic fallback is
|
||
* generated (`"docx-ins-0"`, `"docx-del-3"`, …).
|
||
*
|
||
* @var string
|
||
*/
|
||
public readonly string $revisionId,
|
||
/** @var RevisionKind Semantic kind of this revision. */
|
||
public readonly RevisionKind $kind,
|
||
/** @var RevisionDelta The content changes that make up this revision. */
|
||
public readonly RevisionDelta $delta,
|
||
/** @var ?string Display name of the author who made this change, when available. */
|
||
public readonly ?string $author = null,
|
||
/**
|
||
* ISO-8601 timestamp of the change, when available.
|
||
*
|
||
* Stored as a plain string so this type remains FFI-friendly and
|
||
* unconditionally available without the `chrono` optional dep.
|
||
* DOCX populates this from the `w:date` attribute (e.g.
|
||
* `"2024-03-15T10:30:00Z"`).
|
||
*
|
||
* @var ?string
|
||
*/
|
||
public readonly ?string $timestamp = null,
|
||
/**
|
||
* Best-effort document location for this revision.
|
||
*
|
||
* Resolution is format-dependent and may be `None` when the location
|
||
* cannot be determined (e.g. changes inside table cells before
|
||
* table-cell anchor support is added).
|
||
*
|
||
* @var ?RevisionAnchor
|
||
*/
|
||
public readonly ?RevisionAnchor $anchor = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* The content changes that make up a single revision.
|
||
*
|
||
* For insertions and deletions the `content` field carries the added/removed
|
||
* lines as `DiffLine.Added` / `DiffLine.Removed` entries. For format
|
||
* changes, `content` is empty — the property diff is left as a TODO for a
|
||
* later enrichment pass.
|
||
*/
|
||
final class RevisionDelta
|
||
{
|
||
public function __construct(
|
||
/** @var array<DiffLine> Line-level content changes for this revision. */
|
||
public readonly array $content,
|
||
/** @var array<CellChange> Cell-level table changes for this revision. */
|
||
public readonly array $tableChanges
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Extracted table structure.
|
||
*
|
||
* Represents a table detected and extracted from a document (PDF, image, etc.).
|
||
* Tables are converted to both structured cell data and Markdown format.
|
||
*/
|
||
final class Table
|
||
{
|
||
public function __construct(
|
||
/** @var array<array<string>> Table cells as a 2D vector (rows × columns) */
|
||
public readonly array $cells,
|
||
/** @var string Markdown representation of the table */
|
||
public readonly string $markdown,
|
||
/** @var int Page number where the table was found (1-indexed) */
|
||
public readonly int $pageNumber,
|
||
/**
|
||
* Bounding box of the table on the page (PDF coordinates: x0=left, y0=bottom, x1=right, y1=top).
|
||
* Only populated for PDF-extracted tables when position data is available.
|
||
*
|
||
* @var ?BoundingBox
|
||
*/
|
||
public readonly ?BoundingBox $boundingBox = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Individual table cell with content and optional styling.
|
||
*
|
||
* Future extension point for rich table support with cell-level metadata.
|
||
*/
|
||
final class TableCell
|
||
{
|
||
public function __construct(
|
||
/** @var string Cell content as text */
|
||
public readonly string $content,
|
||
/** @var int Row span (number of rows this cell spans) */
|
||
public readonly int $rowSpan,
|
||
/** @var int Column span (number of columns this cell spans) */
|
||
public readonly int $colSpan,
|
||
/** @var bool Whether this is a header cell */
|
||
public readonly bool $isHeader
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* A URI extracted from a document.
|
||
*
|
||
* Represents any link, reference, or resource pointer found during extraction.
|
||
* The `kind` field classifies the URI semantically, while `label` carries
|
||
* optional human-readable display text.
|
||
*/
|
||
final class ExtractedUri
|
||
{
|
||
public function __construct(
|
||
/** @var string The URL or path string. */
|
||
public readonly string $url,
|
||
/** @var UriKind Semantic classification of the URI. */
|
||
public readonly UriKind $kind,
|
||
/** @var ?string Optional display text / label for the link. */
|
||
public readonly ?string $label = null,
|
||
/** @var ?int Optional page number where the URI was found (1-indexed). */
|
||
public readonly ?int $page = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* MIME type detection response.
|
||
*/
|
||
final class DetectResponse
|
||
{
|
||
public function __construct(
|
||
/** @var string Detected MIME type */
|
||
public readonly string $mimeType,
|
||
/** @var ?string Original filename (if provided) */
|
||
public readonly ?string $filename = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Options controlling how two `ExtractionResult` values are compared.
|
||
*/
|
||
final class DiffOptions
|
||
{
|
||
public function __construct(
|
||
/** @var bool Include metadata changes in the diff. Default: `true`. */
|
||
public readonly bool $includeMetadata,
|
||
/** @var bool Include embedded-children changes in the diff. Default: `true`. */
|
||
public readonly bool $includeEmbedded,
|
||
/**
|
||
* Truncate content to this many characters before diffing.
|
||
*
|
||
* Useful for very large documents where only the first N characters matter.
|
||
* `None` means no truncation.
|
||
*
|
||
* @var ?int
|
||
*/
|
||
public readonly ?int $maxContentChars = null
|
||
) { }
|
||
public static function default(): DiffOptions
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
}
|
||
|
||
/**
|
||
* The complete diff between two `ExtractionResult` values.
|
||
*/
|
||
final class ExtractionDiff
|
||
{
|
||
public function __construct(
|
||
/**
|
||
* Unified-diff hunks for the `content` field.
|
||
*
|
||
* Empty when the content is identical.
|
||
*
|
||
* @var array<DiffHunk>
|
||
*/
|
||
public readonly array $contentDiff,
|
||
/** @var array<Table> Tables present in `b` but not in `a` (by index position, excess right-side tables). */
|
||
public readonly array $tablesAdded,
|
||
/** @var array<Table> Tables present in `a` but not in `b` (by index position, excess left-side tables). */
|
||
public readonly array $tablesRemoved,
|
||
/** @var array<TableDiff> Cell-level changes for table pairs that share the same index and dimensions. */
|
||
public readonly array $tablesChanged,
|
||
/**
|
||
* Metadata difference, encoded as a JSON object with three top-level keys:
|
||
* `added` (keys present in `b` but not `a`), `removed` (keys present in `a`
|
||
* but not `b`), and `changed` (keys whose values differ — each entry is
|
||
* `{ "from": <value-in-a>, "to": <value-in-b> }`).
|
||
*
|
||
* This is NOT RFC 6902 JSON Patch — we deliberately chose a flatter shape
|
||
* to avoid pulling in a json-patch crate. If you need RFC 6902 semantics
|
||
* (with JSON Pointer paths) feed `a.metadata` and `b.metadata` to your
|
||
* preferred json-patch impl directly.
|
||
*
|
||
* @var string
|
||
*/
|
||
public readonly string $metadataChanged,
|
||
/** @var EmbeddedChanges Changes to embedded archive children. */
|
||
public readonly EmbeddedChanges $embeddedChanges
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* A single contiguous hunk in a unified diff.
|
||
*/
|
||
final class DiffHunk
|
||
{
|
||
public function __construct(
|
||
/** @var int Starting line number in the old content (0-indexed). */
|
||
public readonly int $fromLine,
|
||
/** @var int Number of lines from the old content in this hunk. */
|
||
public readonly int $fromCount,
|
||
/** @var int Starting line number in the new content (0-indexed). */
|
||
public readonly int $toLine,
|
||
/** @var int Number of lines from the new content in this hunk. */
|
||
public readonly int $toCount,
|
||
/** @var array<DiffLine> Lines that make up this hunk. */
|
||
public readonly array $lines
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Cell-level changes for a pair of tables that share the same index.
|
||
*/
|
||
final class TableDiff
|
||
{
|
||
public function __construct(
|
||
/** @var int Zero-based index of the table in both `a.tables` and `b.tables`. */
|
||
public readonly int $fromIndex,
|
||
/** @var int Zero-based index in `b.tables` (equal to `from_index` for same-dimension tables). */
|
||
public readonly int $toIndex,
|
||
/** @var array<CellChange> Cell-level changes within the table. */
|
||
public readonly array $cellChanges
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Changes to embedded archive children between two results.
|
||
*/
|
||
final class EmbeddedChanges
|
||
{
|
||
public function __construct(
|
||
/** @var array<ArchiveEntry> Children present in `b` but not in `a` (matched by `path`). */
|
||
public readonly array $added,
|
||
/** @var array<ArchiveEntry> Children present in `a` but not in `b` (matched by `path`). */
|
||
public readonly array $removed,
|
||
/**
|
||
* Children present in both but with differing content (matched by `path`).
|
||
*
|
||
* Each entry holds the diff of the nested `ExtractionResult`.
|
||
*
|
||
* @var array<EmbeddedDiff>
|
||
*/
|
||
public readonly array $changed
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Diff for a single embedded archive entry that appears in both results.
|
||
*/
|
||
final class EmbeddedDiff
|
||
{
|
||
public function __construct(
|
||
/** @var string Archive-relative path identifying this entry. */
|
||
public readonly string $path,
|
||
/** @var ExtractionDiff The recursive diff of the entry's extraction result. */
|
||
public readonly ExtractionDiff $diff
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Preset configurations for common RAG use cases.
|
||
*
|
||
* Each preset combines chunk size, overlap, and embedding model
|
||
* to provide an optimized configuration for specific scenarios.
|
||
*
|
||
* All string fields are owned `String` for FFI compatibility — instances
|
||
* are safe to clone and pass across language boundaries.
|
||
*/
|
||
final class EmbeddingPreset
|
||
{
|
||
public function __construct(
|
||
/** @var string */
|
||
public readonly string $name,
|
||
/** @var int */
|
||
public readonly int $chunkSize,
|
||
/** @var int */
|
||
public readonly int $overlap,
|
||
/** @var string HuggingFace repository name for the model. */
|
||
public readonly string $modelRepo,
|
||
/** @var string Pooling strategy: "cls" or "mean". */
|
||
public readonly string $pooling,
|
||
/** @var string Path to the ONNX model file within the repo. */
|
||
public readonly string $modelFile,
|
||
/** @var int */
|
||
public readonly int $dimensions,
|
||
/** @var string */
|
||
public readonly string $description
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* YAKE-specific parameters.
|
||
*/
|
||
final class YakeParams
|
||
{
|
||
public function __construct(
|
||
/**
|
||
* Window size for co-occurrence analysis (default: 2).
|
||
*
|
||
* Controls the context window for computing co-occurrence statistics.
|
||
*
|
||
* @var int
|
||
*/
|
||
public readonly int $windowSize
|
||
) { }
|
||
public static function default(): YakeParams
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
}
|
||
|
||
/**
|
||
* RAKE-specific parameters.
|
||
*/
|
||
final class RakeParams
|
||
{
|
||
public function __construct(
|
||
/** @var int Minimum word length to consider (default: 1). */
|
||
public readonly int $minWordLength,
|
||
/** @var int Maximum words in a keyword phrase (default: 3). */
|
||
public readonly int $maxWordsPerPhrase
|
||
) { }
|
||
public static function default(): RakeParams
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
}
|
||
|
||
/**
|
||
* Keyword extraction configuration.
|
||
*/
|
||
final class KeywordConfig
|
||
{
|
||
public function __construct(
|
||
/** @var KeywordAlgorithm Algorithm to use for extraction. */
|
||
public readonly KeywordAlgorithm $algorithm,
|
||
/** @var int Maximum number of keywords to extract (default: 10). */
|
||
public readonly int $maxKeywords,
|
||
/**
|
||
* Minimum score threshold (0.0-1.0, default: 0.0).
|
||
*
|
||
* Keywords with scores below this threshold are filtered out.
|
||
* Note: Score ranges differ between algorithms.
|
||
*
|
||
* @var float
|
||
*/
|
||
public readonly float $minScore,
|
||
/**
|
||
* N-gram range for keyword extraction (min, max).
|
||
*
|
||
* (1, 1) = unigrams only
|
||
* (1, 2) = unigrams and bigrams
|
||
* (1, 3) = unigrams, bigrams, and trigrams (default)
|
||
*
|
||
* @var array<int>
|
||
*/
|
||
public readonly array $ngramRange,
|
||
/**
|
||
* Language code for stopword filtering (e.g., "en", "de", "fr").
|
||
*
|
||
* If None, no stopword filtering is applied.
|
||
*
|
||
* @var ?string
|
||
*/
|
||
public readonly ?string $language = null,
|
||
/** @var ?YakeParams YAKE-specific tuning parameters. */
|
||
public readonly ?YakeParams $yakeParams = null,
|
||
/** @var ?RakeParams RAKE-specific tuning parameters. */
|
||
public readonly ?RakeParams $rakeParams = null
|
||
) { }
|
||
public static function default(): KeywordConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
}
|
||
|
||
/**
|
||
* Extracted keyword with metadata.
|
||
*/
|
||
final class Keyword
|
||
{
|
||
public function __construct(
|
||
/** @var string The keyword text. */
|
||
public readonly string $text,
|
||
/** @var float Relevance score (higher is better, algorithm-specific range). */
|
||
public readonly float $score,
|
||
/** @var KeywordAlgorithm Algorithm that extracted this keyword. */
|
||
public readonly KeywordAlgorithm $algorithm,
|
||
/** @var ?array<int> Optional positions where keyword appears in text (character offsets). */
|
||
public readonly ?array $positions = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Configuration for PaddleOCR backend.
|
||
*
|
||
* Configures PaddleOCR text detection and recognition with multi-language support.
|
||
* Uses a builder pattern for convenient configuration.
|
||
*
|
||
* # Examples
|
||
*/
|
||
final class PaddleOcrConfig
|
||
{
|
||
public function __construct(
|
||
/** @var string Language code (e.g., "en", "ch", "jpn", "kor", "deu", "fra") */
|
||
public readonly string $language,
|
||
/**
|
||
* Enable angle classification for rotated text (default: false).
|
||
* Can misfire on short text regions, rotating crops incorrectly before recognition.
|
||
*
|
||
* @var bool
|
||
*/
|
||
public readonly bool $useAngleCls,
|
||
/** @var bool Enable table structure detection (default: false) */
|
||
public readonly bool $enableTableDetection,
|
||
/**
|
||
* Database threshold for text detection (default: 0.3)
|
||
* Range: 0.0-1.0, higher values require more confident detections
|
||
*
|
||
* @var float
|
||
*/
|
||
public readonly float $detDbThresh,
|
||
/**
|
||
* Box threshold for text bounding box refinement (default: 0.5)
|
||
* Range: 0.0-1.0
|
||
*
|
||
* @var float
|
||
*/
|
||
public readonly float $detDbBoxThresh,
|
||
/**
|
||
* Unclip ratio for expanding text bounding boxes (default: 1.6)
|
||
* Controls the expansion of detected text regions
|
||
*
|
||
* @var float
|
||
*/
|
||
public readonly float $detDbUnclipRatio,
|
||
/**
|
||
* Maximum side length for detection image (default: 960)
|
||
* Larger images may be resized to this limit for faster inference
|
||
*
|
||
* @var int
|
||
*/
|
||
public readonly int $detLimitSideLen,
|
||
/**
|
||
* Batch size for recognition inference (default: 6)
|
||
* Number of text regions to process simultaneously
|
||
*
|
||
* @var int
|
||
*/
|
||
public readonly int $recBatchNum,
|
||
/**
|
||
* Padding in pixels added around the image before detection (default: 10).
|
||
* Large values can include surrounding content like table gridlines.
|
||
*
|
||
* @var int
|
||
*/
|
||
public readonly int $padding,
|
||
/**
|
||
* Minimum recognition confidence score for text lines (default: 0.5).
|
||
* Text regions with recognition confidence below this threshold are discarded.
|
||
* Matches PaddleOCR Python's `drop_score` parameter.
|
||
* Range: 0.0-1.0
|
||
*
|
||
* @var float
|
||
*/
|
||
public readonly float $dropScore,
|
||
/**
|
||
* Model tier controlling detection/recognition model size and accuracy trade-off.
|
||
* - `"mobile"` (default): Lightweight models (~4.5MB detection, ~16.5MB recognition), fast download and inference
|
||
* - `"server"`: Large, high-accuracy models (~88MB detection, ~84MB recognition), best for GPU or complex documents
|
||
*
|
||
* @var string
|
||
*/
|
||
public readonly string $modelTier,
|
||
/** @var ?string Optional custom cache directory for model files */
|
||
public readonly ?string $cacheDir = null
|
||
) { }
|
||
public function withCacheDir(string $path): PaddleOcrConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
public function withTableDetection(bool $enable): PaddleOcrConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
public function withAngleCls(bool $enable): PaddleOcrConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
public function withDetDbThresh(float $threshold): PaddleOcrConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
public function withDetDbBoxThresh(float $threshold): PaddleOcrConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
public function withDetDbUnclipRatio(float $ratio): PaddleOcrConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
public function withDetLimitSideLen(int $length): PaddleOcrConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
public function withRecBatchNum(int $batch_size): PaddleOcrConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
public function withDropScore(float $score): PaddleOcrConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
public function withPadding(int $padding): PaddleOcrConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
public function withModelTier(string $tier): PaddleOcrConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
public static function default(): PaddleOcrConfig
|
||
{ throw new \RuntimeException('Not implemented — provided by the native extension.'); }
|
||
}
|
||
|
||
/**
|
||
* Combined paths to all models needed for OCR (backward compatibility).
|
||
*/
|
||
final class ModelPaths
|
||
{
|
||
public function __construct(
|
||
/** @var string Path to the detection model directory. */
|
||
public readonly string $detModel,
|
||
/** @var string Path to the classification model directory. */
|
||
public readonly string $clsModel,
|
||
/** @var string Path to the recognition model directory. */
|
||
public readonly string $recModel,
|
||
/** @var string Path to the character dictionary file. */
|
||
public readonly string $dictFile
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Document orientation detection result.
|
||
*/
|
||
final class OrientationResult
|
||
{
|
||
public function __construct(
|
||
/** @var int Detected orientation in degrees (0, 90, 180, or 270). */
|
||
public readonly int $degrees,
|
||
/** @var float Confidence score (0.0-1.0). */
|
||
public readonly float $confidence
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Bounding box in original image coordinates (x1, y1) top-left, (x2, y2) bottom-right.
|
||
*/
|
||
final class BBox
|
||
{
|
||
public function __construct(
|
||
/** @var float */
|
||
public readonly float $x1,
|
||
/** @var float */
|
||
public readonly float $y1,
|
||
/** @var float */
|
||
public readonly float $x2,
|
||
/** @var float */
|
||
public readonly float $y2
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* A single layout detection result.
|
||
*/
|
||
final class LayoutDetection
|
||
{
|
||
public function __construct(
|
||
/** @var LayoutClass */
|
||
public readonly LayoutClass $className,
|
||
/** @var float */
|
||
public readonly float $confidence,
|
||
/** @var BBox */
|
||
public readonly BBox $bbox
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Pre-computed table markdown for a table detection region.
|
||
*
|
||
* Produced by the TATR-based table structure recognizer and surfaced as part of
|
||
* layout-aware OCR results. The struct lives here (under `layout-types`, pure-Rust)
|
||
* so that consumers who do not enable `layout-detection` (ORT) can still reference
|
||
* the type in their own code.
|
||
*/
|
||
final class RecognizedTable
|
||
{
|
||
public function __construct(
|
||
/** @var BBox Detection bbox that this table corresponds to (for matching). */
|
||
public readonly BBox $detectionBbox,
|
||
/** @var array<array<string>> Table cells as a 2D vector (rows × columns). */
|
||
public readonly array $cells,
|
||
/** @var string Rendered markdown table. */
|
||
public readonly string $markdown
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Page-level detection result containing all detections and page metadata.
|
||
*/
|
||
final class DetectionResult
|
||
{
|
||
public function __construct(
|
||
/** @var int */
|
||
public readonly int $pageWidth,
|
||
/** @var int */
|
||
public readonly int $pageHeight,
|
||
/** @var array<LayoutDetection> */
|
||
public readonly array $detections
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* Embedded file descriptor extracted from the PDF name tree.
|
||
*/
|
||
final class EmbeddedFile
|
||
{
|
||
public function __construct(
|
||
/** @var string The filename as stored in the PDF name tree. */
|
||
public readonly string $name,
|
||
/** @var string Raw file bytes from the embedded stream (already decompressed by lopdf). */
|
||
public readonly string $data,
|
||
/**
|
||
* Compressed byte count of the original stream (before decompression).
|
||
*
|
||
* Used by callers to compute the decompression ratio and detect zip-bomb-style
|
||
* attacks that embed a tiny compressed stream expanding to gigabytes of data.
|
||
*
|
||
* @var int
|
||
*/
|
||
public readonly int $compressedSize,
|
||
/** @var ?string MIME type if specified in the filespec, otherwise `None`. */
|
||
public readonly ?string $mimeType = null
|
||
) { }
|
||
}
|
||
|
||
/**
|
||
* PDF-specific metadata.
|
||
*
|
||
* Contains metadata fields specific to PDF documents that are not in the common
|
||
* `Metadata` structure. Common fields like title, authors, keywords, and dates
|
||
* are at the `Metadata` level.
|
||
*/
|
||
final class PdfMetadata
|
||
{
|
||
public function __construct(
|
||
/** @var ?string PDF version (e.g., "1.7", "2.0") */
|
||
public readonly ?string $pdfVersion = null,
|
||
/** @var ?string PDF producer (application that created the PDF) */
|
||
public readonly ?string $producer = null,
|
||
/** @var ?bool Whether the PDF is encrypted/password-protected */
|
||
public readonly ?bool $isEncrypted = null,
|
||
/** @var ?int First page width in points (1/72 inch) */
|
||
public readonly ?int $width = null,
|
||
/** @var ?int First page height in points (1/72 inch) */
|
||
public readonly ?int $height = null,
|
||
/** @var ?int Total number of pages in the PDF document */
|
||
public readonly ?int $pageCount = null
|
||
) { }
|
||
}
|
||
|
||
enum ExecutionProviderType: string
|
||
{
|
||
case Auto = 'Auto';
|
||
case Cpu = 'Cpu';
|
||
case CoreMl = 'CoreMl';
|
||
case Cuda = 'Cuda';
|
||
case TensorRt = 'TensorRt';
|
||
}
|
||
|
||
enum OutputFormat: string
|
||
{
|
||
case Plain = 'Plain';
|
||
case Markdown = 'Markdown';
|
||
case Djot = 'Djot';
|
||
case Html = 'Html';
|
||
case Json = 'Json';
|
||
case Structured = 'Structured';
|
||
case Custom = 'Custom';
|
||
}
|
||
|
||
enum HtmlTheme: string
|
||
{
|
||
case Default = 'Default';
|
||
case GitHub = 'GitHub';
|
||
case Dark = 'Dark';
|
||
case Light = 'Light';
|
||
case Unstyled = 'Unstyled';
|
||
}
|
||
|
||
enum TableModel: string
|
||
{
|
||
case Tatr = 'tatr';
|
||
case SlanetWired = 'slanet_wired';
|
||
case SlanetWireless = 'slanet_wireless';
|
||
case SlanetPlus = 'slanet_plus';
|
||
case SlanetAuto = 'slanet_auto';
|
||
case Disabled = 'disabled';
|
||
}
|
||
|
||
enum ChunkerType: string
|
||
{
|
||
case Text = 'Text';
|
||
case Markdown = 'Markdown';
|
||
case Yaml = 'Yaml';
|
||
case Semantic = 'Semantic';
|
||
}
|
||
|
||
/**
|
||
* How chunk size is measured.
|
||
*
|
||
* Defaults to `Characters` (Unicode character count). When using token-based sizing,
|
||
* chunks are sized by token count according to the specified tokenizer.
|
||
*
|
||
* Token-based sizing uses HuggingFace tokenizers loaded at runtime. Any tokenizer
|
||
* available on HuggingFace Hub can be used, including OpenAI-compatible tokenizers
|
||
* (e.g., `Xenova/gpt-4o`, `Xenova/cl100k_base`).
|
||
*/
|
||
final class ChunkSizing
|
||
{
|
||
}
|
||
|
||
/**
|
||
* Embedding model types supported by Kreuzberg.
|
||
*/
|
||
final class EmbeddingModelType
|
||
{
|
||
}
|
||
|
||
enum CodeContentMode: string
|
||
{
|
||
case Chunks = 'chunks';
|
||
case Raw = 'raw';
|
||
case Structure = 'structure';
|
||
}
|
||
|
||
enum ListType: string
|
||
{
|
||
case Bullet = 'Bullet';
|
||
case Numbered = 'Numbered';
|
||
case Lettered = 'Lettered';
|
||
case Indented = 'Indented';
|
||
}
|
||
|
||
enum OcrBackendType: string
|
||
{
|
||
case Tesseract = 'Tesseract';
|
||
case EasyOCR = 'EasyOCR';
|
||
case PaddleOCR = 'PaddleOCR';
|
||
case Custom = 'Custom';
|
||
}
|
||
|
||
enum ProcessingStage: string
|
||
{
|
||
case Early = 'Early';
|
||
case Middle = 'Middle';
|
||
case Late = 'Late';
|
||
}
|
||
|
||
enum ReductionLevel: string
|
||
{
|
||
case Off = 'Off';
|
||
case Light = 'Light';
|
||
case Moderate = 'Moderate';
|
||
case Aggressive = 'Aggressive';
|
||
case Maximum = 'Maximum';
|
||
}
|
||
|
||
enum PdfAnnotationType: string
|
||
{
|
||
case Text = 'text';
|
||
case Highlight = 'highlight';
|
||
case Link = 'link';
|
||
case Stamp = 'stamp';
|
||
case Underline = 'underline';
|
||
case StrikeOut = 'strike_out';
|
||
case Other = 'other';
|
||
}
|
||
|
||
enum BlockType: string
|
||
{
|
||
case Paragraph = 'paragraph';
|
||
case Heading = 'heading';
|
||
case Blockquote = 'blockquote';
|
||
case CodeBlock = 'code_block';
|
||
case ListItem = 'list_item';
|
||
case OrderedList = 'ordered_list';
|
||
case BulletList = 'bullet_list';
|
||
case TaskList = 'task_list';
|
||
case DefinitionList = 'definition_list';
|
||
case DefinitionTerm = 'definition_term';
|
||
case DefinitionDescription = 'definition_description';
|
||
case Div = 'div';
|
||
case Section = 'section';
|
||
case ThematicBreak = 'thematic_break';
|
||
case RawBlock = 'raw_block';
|
||
case MathDisplay = 'math_display';
|
||
}
|
||
|
||
enum InlineType: string
|
||
{
|
||
case Text = 'text';
|
||
case Strong = 'strong';
|
||
case Emphasis = 'emphasis';
|
||
case Highlight = 'highlight';
|
||
case Subscript = 'subscript';
|
||
case Superscript = 'superscript';
|
||
case Insert = 'insert';
|
||
case Delete = 'delete';
|
||
case Code = 'code';
|
||
case Link = 'link';
|
||
case Image = 'image';
|
||
case Span = 'span';
|
||
case Math = 'math';
|
||
case RawInline = 'raw_inline';
|
||
case FootnoteRef = 'footnote_ref';
|
||
case Symbol = 'symbol';
|
||
}
|
||
|
||
enum RelationshipKind: string
|
||
{
|
||
case FootnoteReference = 'footnote_reference';
|
||
case CitationReference = 'citation_reference';
|
||
case InternalLink = 'internal_link';
|
||
case Caption = 'caption';
|
||
case Label = 'label';
|
||
case TocEntry = 'toc_entry';
|
||
case CrossReference = 'cross_reference';
|
||
}
|
||
|
||
enum ContentLayer: string
|
||
{
|
||
case Body = 'body';
|
||
case Header = 'header';
|
||
case Footer = 'footer';
|
||
case Footnote = 'footnote';
|
||
}
|
||
|
||
/**
|
||
* Tagged enum for node content. Each variant carries only type-specific data.
|
||
*
|
||
* Uses `#[serde(tag = "node_type")]` to avoid "type" keyword collision in
|
||
* Go/Java/TypeScript bindings.
|
||
*/
|
||
final class NodeContent
|
||
{
|
||
}
|
||
|
||
/**
|
||
* Types of inline text annotations.
|
||
*/
|
||
final class AnnotationKind
|
||
{
|
||
}
|
||
|
||
enum ExtractionMethod: string
|
||
{
|
||
case Native = 'native';
|
||
case Ocr = 'ocr';
|
||
case Mixed = 'mixed';
|
||
}
|
||
|
||
enum ChunkType: string
|
||
{
|
||
case Heading = 'heading';
|
||
case PartyList = 'party_list';
|
||
case Definitions = 'definitions';
|
||
case OperativeClause = 'operative_clause';
|
||
case SignatureBlock = 'signature_block';
|
||
case Schedule = 'schedule';
|
||
case TableLike = 'table_like';
|
||
case Formula = 'formula';
|
||
case CodeBlock = 'code_block';
|
||
case Image = 'image';
|
||
case OrgChart = 'org_chart';
|
||
case Diagram = 'diagram';
|
||
case Unknown = 'unknown';
|
||
}
|
||
|
||
enum ImageKind: string
|
||
{
|
||
case Photograph = 'photograph';
|
||
case Diagram = 'diagram';
|
||
case Chart = 'chart';
|
||
case Drawing = 'drawing';
|
||
case TextBlock = 'text_block';
|
||
case Decoration = 'decoration';
|
||
case Logo = 'logo';
|
||
case Icon = 'icon';
|
||
case TileFragment = 'tile_fragment';
|
||
case Mask = 'mask';
|
||
case PageRaster = 'page_raster';
|
||
case Unknown = 'unknown';
|
||
}
|
||
|
||
enum ResultFormat: string
|
||
{
|
||
case Unified = 'unified';
|
||
case ElementBased = 'element_based';
|
||
}
|
||
|
||
enum ElementType: string
|
||
{
|
||
case Title = 'title';
|
||
case NarrativeText = 'narrative_text';
|
||
case Heading = 'heading';
|
||
case ListItem = 'list_item';
|
||
case Table = 'table';
|
||
case Image = 'image';
|
||
case PageBreak = 'page_break';
|
||
case CodeBlock = 'code_block';
|
||
case BlockQuote = 'block_quote';
|
||
case Footer = 'footer';
|
||
case Header = 'header';
|
||
}
|
||
|
||
/**
|
||
* Format-specific metadata (discriminated union).
|
||
*
|
||
* Only one format type can exist per extraction result. This provides
|
||
* type-safe, clean metadata without nested optionals.
|
||
*/
|
||
final class FormatMetadata
|
||
{
|
||
}
|
||
|
||
enum TextDirection: string
|
||
{
|
||
case LeftToRight = 'ltr';
|
||
case RightToLeft = 'rtl';
|
||
case Auto = 'auto';
|
||
}
|
||
|
||
enum LinkType: string
|
||
{
|
||
case Anchor = 'Anchor';
|
||
case Internal = 'Internal';
|
||
case External = 'External';
|
||
case Email = 'Email';
|
||
case Phone = 'Phone';
|
||
case Other = 'Other';
|
||
}
|
||
|
||
enum ImageType: string
|
||
{
|
||
case DataUri = 'data-uri';
|
||
case InlineSvg = 'inline-svg';
|
||
case External = 'External';
|
||
case Relative = 'Relative';
|
||
}
|
||
|
||
enum StructuredDataType: string
|
||
{
|
||
case JsonLd = 'json-ld';
|
||
case Microdata = 'Microdata';
|
||
case RDFa = 'rdfa';
|
||
}
|
||
|
||
/**
|
||
* Bounding geometry for an OCR element.
|
||
*
|
||
* Supports both axis-aligned rectangles (from Tesseract) and 4-point quadrilaterals
|
||
* (from PaddleOCR and rotated text detection).
|
||
*/
|
||
final class OcrBoundingGeometry
|
||
{
|
||
}
|
||
|
||
enum OcrElementLevel: string
|
||
{
|
||
case Word = 'word';
|
||
case Line = 'line';
|
||
case Block = 'block';
|
||
case Page = 'page';
|
||
}
|
||
|
||
enum PageUnitType: string
|
||
{
|
||
case Page = 'page';
|
||
case Slide = 'slide';
|
||
case Sheet = 'sheet';
|
||
}
|
||
|
||
/**
|
||
* A single line in a unified-diff hunk.
|
||
*
|
||
* Defined here (rather than only in `crate.diff`) so `RevisionDelta` can
|
||
* reference it unconditionally, without requiring the `diff` Cargo feature.
|
||
* `crate.diff` re-exports this type verbatim.
|
||
*/
|
||
final class DiffLine
|
||
{
|
||
}
|
||
|
||
enum RevisionKind: string
|
||
{
|
||
case Insertion = 'insertion';
|
||
case Deletion = 'deletion';
|
||
case FormatChange = 'format_change';
|
||
case Comment = 'comment';
|
||
}
|
||
|
||
/**
|
||
* Best-effort document location for a revision.
|
||
*/
|
||
final class RevisionAnchor
|
||
{
|
||
}
|
||
|
||
enum UriKind: string
|
||
{
|
||
case Hyperlink = 'hyperlink';
|
||
case Image = 'image';
|
||
case Anchor = 'anchor';
|
||
case Citation = 'citation';
|
||
case Reference = 'reference';
|
||
case Email = 'email';
|
||
}
|
||
|
||
enum KeywordAlgorithm: string
|
||
{
|
||
case Yake = 'Yake';
|
||
case Rake = 'Rake';
|
||
}
|
||
|
||
enum PSMMode: string
|
||
{
|
||
case OsdOnly = 'OsdOnly';
|
||
case AutoOsd = 'AutoOsd';
|
||
case AutoOnly = 'AutoOnly';
|
||
case Auto = 'Auto';
|
||
case SingleColumn = 'SingleColumn';
|
||
case SingleBlockVertical = 'SingleBlockVertical';
|
||
case SingleBlock = 'SingleBlock';
|
||
case SingleLine = 'SingleLine';
|
||
case SingleWord = 'SingleWord';
|
||
case CircleWord = 'CircleWord';
|
||
case SingleChar = 'SingleChar';
|
||
}
|
||
|
||
enum PaddleLanguage: string
|
||
{
|
||
case English = 'English';
|
||
case Chinese = 'Chinese';
|
||
case Japanese = 'Japanese';
|
||
case Korean = 'Korean';
|
||
case German = 'German';
|
||
case French = 'French';
|
||
case Latin = 'Latin';
|
||
case Cyrillic = 'Cyrillic';
|
||
case TraditionalChinese = 'TraditionalChinese';
|
||
case Thai = 'Thai';
|
||
case Greek = 'Greek';
|
||
case EastSlavic = 'EastSlavic';
|
||
case Arabic = 'Arabic';
|
||
case Devanagari = 'Devanagari';
|
||
case Tamil = 'Tamil';
|
||
case Telugu = 'Telugu';
|
||
}
|
||
|
||
enum LayoutClass: string
|
||
{
|
||
case Caption = 'caption';
|
||
case Footnote = 'footnote';
|
||
case Formula = 'formula';
|
||
case ListItem = 'list_item';
|
||
case PageFooter = 'page_footer';
|
||
case PageHeader = 'page_header';
|
||
case Picture = 'picture';
|
||
case SectionHeader = 'section_header';
|
||
case Table = 'table';
|
||
case Text = 'text';
|
||
case Title = 'title';
|
||
case DocumentIndex = 'document_index';
|
||
case Code = 'code';
|
||
case CheckboxSelected = 'checkbox_selected';
|
||
case CheckboxUnselected = 'checkbox_unselected';
|
||
case Form = 'form';
|
||
case KeyValueRegion = 'key_value_region';
|
||
}
|
||
|
||
class KreuzbergApi
|
||
{
|
||
public static function extractBytes(string $content, string $mime_type, \Kreuzberg\ExtractionConfig $config): \Kreuzberg\ExtractionResult { throw new \RuntimeException('Not implemented.'); }
|
||
public static function extractFile(string $path, ?string $mime_type = null, ?\Kreuzberg\ExtractionConfig $config = null): \Kreuzberg\ExtractionResult { throw new \RuntimeException('Not implemented.'); }
|
||
public static function extractFileSync(string $path, ?string $mime_type = null, ?\Kreuzberg\ExtractionConfig $config = null): \Kreuzberg\ExtractionResult { throw new \RuntimeException('Not implemented.'); }
|
||
public static function extractBytesSync(string $content, string $mime_type, \Kreuzberg\ExtractionConfig $config): \Kreuzberg\ExtractionResult { throw new \RuntimeException('Not implemented.'); }
|
||
/**
|
||
* @param array<\Kreuzberg\BatchFileItem> $items
|
||
* @param \Kreuzberg\ExtractionConfig $config
|
||
* @return array<\Kreuzberg\ExtractionResult>
|
||
*/
|
||
public static function batchExtractFilesSync(array $items, \Kreuzberg\ExtractionConfig $config): array { throw new \RuntimeException('Not implemented.'); }
|
||
/**
|
||
* @param array<\Kreuzberg\BatchBytesItem> $items
|
||
* @param \Kreuzberg\ExtractionConfig $config
|
||
* @return array<\Kreuzberg\ExtractionResult>
|
||
*/
|
||
public static function batchExtractBytesSync(array $items, \Kreuzberg\ExtractionConfig $config): array { throw new \RuntimeException('Not implemented.'); }
|
||
/**
|
||
* @param array<\Kreuzberg\BatchFileItem> $items
|
||
* @param \Kreuzberg\ExtractionConfig $config
|
||
* @return array<\Kreuzberg\ExtractionResult>
|
||
*/
|
||
public static function batchExtractFiles(array $items, \Kreuzberg\ExtractionConfig $config): array { throw new \RuntimeException('Not implemented.'); }
|
||
/**
|
||
* @param array<\Kreuzberg\BatchBytesItem> $items
|
||
* @param \Kreuzberg\ExtractionConfig $config
|
||
* @return array<\Kreuzberg\ExtractionResult>
|
||
*/
|
||
public static function batchExtractBytes(array $items, \Kreuzberg\ExtractionConfig $config): array { throw new \RuntimeException('Not implemented.'); }
|
||
public static function detectMimeTypeFromBytes(string $content): string { throw new \RuntimeException('Not implemented.'); }
|
||
/**
|
||
* @param string $mime_type
|
||
* @return array<string>
|
||
*/
|
||
public static function getExtensionsForMime(string $mime_type): array { throw new \RuntimeException('Not implemented.'); }
|
||
public static function clearEmbeddingBackends(): void { }
|
||
/**
|
||
* @return array<string>
|
||
*/
|
||
public static function listEmbeddingBackends(): array { throw new \RuntimeException('Not implemented.'); }
|
||
/**
|
||
* @return array<string>
|
||
*/
|
||
public static function listDocumentExtractors(): array { throw new \RuntimeException('Not implemented.'); }
|
||
public static function clearDocumentExtractors(): void { }
|
||
/**
|
||
* @return array<string>
|
||
*/
|
||
public static function listOcrBackends(): array { throw new \RuntimeException('Not implemented.'); }
|
||
public static function clearOcrBackends(): void { }
|
||
/**
|
||
* @return array<string>
|
||
*/
|
||
public static function listPostProcessors(): array { throw new \RuntimeException('Not implemented.'); }
|
||
public static function clearPostProcessors(): void { }
|
||
/**
|
||
* @return array<string>
|
||
*/
|
||
public static function listRenderers(): array { throw new \RuntimeException('Not implemented.'); }
|
||
public static function clearRenderers(): void { }
|
||
/**
|
||
* @return array<string>
|
||
*/
|
||
public static function listValidators(): array { throw new \RuntimeException('Not implemented.'); }
|
||
public static function clearValidators(): void { }
|
||
public static function compare(\Kreuzberg\ExtractionResult $a, \Kreuzberg\ExtractionResult $b, \Kreuzberg\DiffOptions $opts): \Kreuzberg\ExtractionDiff { throw new \RuntimeException('Not implemented.'); }
|
||
/**
|
||
* @param array<string> $texts
|
||
* @param \Kreuzberg\EmbeddingConfig $config
|
||
* @return array<array<float>>
|
||
*/
|
||
public static function embedTextsAsync(array $texts, \Kreuzberg\EmbeddingConfig $config): array { throw new \RuntimeException('Not implemented.'); }
|
||
public static function renderPdfPageToPng(string $pdf_bytes, int $page_index, ?int $dpi = null, ?string $password = null): string { throw new \RuntimeException('Not implemented.'); }
|
||
public static function detectMimeType(string $path, bool $check_exists): string { throw new \RuntimeException('Not implemented.'); }
|
||
/**
|
||
* @param array<string> $texts
|
||
* @param \Kreuzberg\EmbeddingConfig $config
|
||
* @return array<array<float>>
|
||
*/
|
||
public static function embedTexts(array $texts, \Kreuzberg\EmbeddingConfig $config): array { throw new \RuntimeException('Not implemented.'); }
|
||
public static function getEmbeddingPreset(string $name): ?\Kreuzberg\EmbeddingPreset { throw new \RuntimeException('Not implemented.'); }
|
||
/**
|
||
* @return array<string>
|
||
*/
|
||
public static function listEmbeddingPresets(): array { throw new \RuntimeException('Not implemented.'); }
|
||
public static function registerOcrBackend(\Kreuzberg\OcrBackend $backend): void { }
|
||
public static function unregisterOcrBackend(string $name): void { }
|
||
public static function clearOcrBackends(): void { }
|
||
public static function registerPostProcessor(\Kreuzberg\PostProcessor $backend): void { }
|
||
public static function unregisterPostProcessor(string $name): void { }
|
||
public static function clearPostProcessors(): void { }
|
||
public static function registerValidator(\Kreuzberg\Validator $backend): void { }
|
||
public static function unregisterValidator(string $name): void { }
|
||
public static function clearValidators(): void { }
|
||
public static function registerEmbeddingBackend(\Kreuzberg\EmbeddingBackend $backend): void { }
|
||
public static function unregisterEmbeddingBackend(string $name): void { }
|
||
public static function clearEmbeddingBackends(): void { }
|
||
public static function registerDocumentExtractor(\Kreuzberg\DocumentExtractor $backend): void { }
|
||
public static function unregisterDocumentExtractor(string $name): void { }
|
||
public static function clearDocumentExtractors(): void { }
|
||
public static function registerRenderer(\Kreuzberg\Renderer $backend): void { }
|
||
public static function unregisterRenderer(string $name): void { }
|
||
public static function clearRenderers(): void { }
|
||
}
|
||
|
||
} // end namespace
|